openapi: 3.1.1
info:
  title: Peridio Admin API
  version: 1
  license:
    name: Peridio
    url: https://github.com/peridio/parasola/blob/main/LICENSE
  description: >
    # 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:


    ```text

    /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](#section/Expanding-Responses/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:


    ```text

    /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](#section/Expanding-Responses/Nested-Expands).


    ## Expanding Multiple Fields


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


    For example:


    ```text

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


    ```text

    /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](#section/Expanding-Responses/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.


    ```text

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


    ## Queries


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


    For example:


    ```text

    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:


    ```text

    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:


    ```text

    summary~'zoro\'s three sword style'

    ```


    ### Boolean


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


    For example:


    ```text

    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:


    ```text

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

    ```


    ### Numeric


    Numeric values are supplied as-is without single quotes.


    For example:


    ```text

    berries:100000000

    ```
servers:
  - url: https://api.cremini.peridio.com
security:
  - api_key: []
    api_key_v2: []
tags:
  - name: Bundles
    id: bundles
  - name: Users
    id: users
  - name: Artifacts
    id: artifacts
  - name: Artifact Versions
    id: artifact-versions
  - name: Binaries
    id: binaries
  - name: Binary Parts
    id: binary-parts
  - name: Binary Signatures
    id: binary-signatures
  - name: Signing Keys
    id: signing-keys
  - name: CA Certificates
    id: ca-certificates
  - name: Cohorts
    id: cohorts
  - name: Device Certificates
    id: device-certificates
  - name: Devices
    id: devices
  - name: Products
    id: products
  - name: Releases
    id: releases
  - name: Tunnels
    id: tunnels
  - name: API Key Events
    id: api-key-events
    description: Events created due to API Key activity.
  - name: Device Events
    id: device-events
    description: Events created due to device activity.
  - name: Webhook Events
    id: webhook-events
    description: Events created due to webhook activity.
  - name: Webhooks
    id: webhooks
  - name: Web Console
    id: web-console
  - name: Events
    id: events
  - name: Legacy CA Certificates
    id: legacy-ca-firmware
  - name: Legacy Device Certificates
    id: legacy-device-certificates
  - name: Legacy Devices
    id: legacy-devices
  - name: Deployments
    id: deployments
    description: >-
      This functionality has been superceded by [bundles](#bundles) and
      [releases](#releases).
  - name: Deployments v2
    id: deployments-v2
    description: >-
      This functionality has been superceded by [bundles](#bundles) and
      [releases](#releases).
  - name: Firmware
    id: firmware
    description: >
      **Deprecated**


      This functionality has been superceded by [artifacts](#artifacts),
      [artifact versions](#artifact-versions), and [binaries](#binaries).
  - name: Firmware v2
    id: firmware-v2
    description: >
      **Deprecated**


      This functionality has been superceded by [artifacts](#artifacts),
      [artifact versions](#artifact-versions), and [binaries](#binaries).
x-tagGroups:
  - name: Account Management
    tags:
      - Users
  - name: Binary Management
    tags:
      - Artifacts
      - Artifact Versions
      - Binaries
      - Binary Parts
      - Binary Signatures
      - Signing Keys
  - name: Remote Access
    tags:
      - Tunnels
      - Web Console
  - name: Device Management
    tags:
      - CA Certificates
      - Cohorts
      - Device Certificates
      - Devices
      - Products
  - name: Integration Management
    tags:
      - Webhooks
  - name: Release Management
    tags:
      - Bundles
      - Releases
  - name: Events
    tags:
      - Events
      - API Key Events
      - Device Events
      - Webhook Events
  - name: Legacy
    tags:
      - Legacy CA Certificates
      - Legacy Device Certificates
      - Legacy Devices
      - Deployments
      - Deployments v2
      - Firmware
      - Firmware v2
paths:
  /artifacts:
    post:
      operationId: create-an-artifact
      summary: Create an artifact
      tags:
        - Artifacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-artifact'
                description:
                  $ref: '#/components/schemas/artifact-description'
                id:
                  $ref: '#/components/schemas/custom-id'
                name:
                  $ref: '#/components/schemas/artifact-name'
              required:
                - name
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact:
                    $ref: '#/components/schemas/artifact'
    get:
      operationId: list-artifacts
      summary: List artifacts
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`description`||`:`, `~`|string|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`name`||`:`, `~`, `-`|string|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Artifacts
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifacts:
                    $ref: '#/components/schemas/array-of-artifacts'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /artifacts/{artifact_prn}:
    get:
      operationId: retrieve-an-artifact
      summary: Retrieve an artifact
      tags:
        - Artifacts
      parameters:
        - name: artifact_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact:
                    $ref: '#/components/schemas/artifact'
    patch:
      operationId: update-an-artifact
      summary: Update an artifact
      tags:
        - Artifacts
      parameters:
        - name: artifact_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-artifact'
                description:
                  $ref: '#/components/schemas/artifact-description'
                name:
                  $ref: '#/components/schemas/artifact-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact:
                    $ref: '#/components/schemas/artifact'
    delete:
      operationId: delete-an-artifact
      summary: Delete an artifact
      tags:
        - Artifacts
      parameters:
        - name: artifact_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /artifact_versions:
    post:
      operationId: create-an-artifact-version
      summary: Create an artifact version
      tags:
        - Artifact Versions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                artifact_prn:
                  $ref: '#/components/schemas/prn'
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-artifact-version'
                description:
                  $ref: '#/components/schemas/artifact-version-description'
                id:
                  $ref: '#/components/schemas/custom-id'
                version:
                  $ref: '#/components/schemas/artifact-version-version'
              required:
                - artifact_prn
                - version
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact_version:
                    $ref: '#/components/schemas/artifact-version'
    get:
      operationId: list-artifact-versions
      summary: List artifact versions
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`artifact_prn`||`:`|string|
        |`description`||`:`, `~`|string|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Artifact Versions
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact_versions:
                    $ref: '#/components/schemas/array-of-artifact-versions'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /artifact_versions/{artifact_version_prn}:
    get:
      operationId: retrieve-an-artifact-version
      summary: Retrieve artifact version
      tags:
        - Artifact Versions
      parameters:
        - name: artifact_version_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact_version:
                    $ref: '#/components/schemas/artifact-version'
    patch:
      operationId: update-an-artifact-version
      summary: Update an artifact version
      tags:
        - Artifact Versions
      parameters:
        - name: artifact_version_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-artifact-version'
                description:
                  $ref: '#/components/schemas/artifact-version-description'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  artifact_version:
                    $ref: '#/components/schemas/artifact-version'
    delete:
      operationId: delete-an-artifact-version
      summary: Delete an artifact version
      tags:
        - Artifact Versions
      parameters:
        - name: artifact_version_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /binaries:
    post:
      operationId: create-a-binary
      summary: Create a binary
      description: |
        Create a binary record.
      tags:
        - Binaries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                artifact_version_prn:
                  $ref: '#/components/schemas/prn'
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-binary'
                description:
                  $ref: '#/components/schemas/binary-description'
                hash:
                  $ref: '#/components/schemas/binary-hash'
                id:
                  $ref: '#/components/schemas/custom-id'
                size:
                  $ref: '#/components/schemas/binary-size'
                target:
                  $ref: '#/components/schemas/target-triplet'
              required:
                - artifact_version_prn
                - hash
                - size
                - target
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary:
                    $ref: '#/components/schemas/binary'
    get:
      operationId: list-binaries
      summary: List binaries
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`artifact_version_prn`||`:`|string|
        |`description`||`:`, `~`|string|
        |`hash`||`:`|string|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`||`:`|string|
        |`size`||`:`, `>`, `>=`, `<`, `<=` |integer|
        |`target`||`:`, `~`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Binaries
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binaries:
                    $ref: '#/components/schemas/array-of-binaries'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /binaries/{binary_prn}:
    get:
      operationId: retrieve-a-binary
      summary: Retrieve a binary
      tags:
        - Binaries
      parameters:
        - name: binary_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary:
                    $ref: '#/components/schemas/binary'
    patch:
      operationId: update-a-binary
      summary: Update a binary
      tags:
        - Binaries
      parameters:
        - name: binary_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                custom_metadata:
                  $ref: '#/components/schemas/custom-metadata-binary'
                description:
                  $ref: '#/components/schemas/binary-description'
                state:
                  $ref: '#/components/schemas/binary-state'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary:
                    $ref: '#/components/schemas/binary'
    delete:
      operationId: delete-a-binary
      summary: Delete a binary
      tags:
        - Binaries
      parameters:
        - name: binary_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /binaries/{binary_prn}/parts/{index}:
    put:
      operationId: create-a-binary-part
      summary: Create a Binary Part
      description: |
        Create a binary part.
      tags:
        - Binary Parts
      parameters:
        - name: binary_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
        - name: index
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/binary-part-index'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                expected_binary_size:
                  $ref: '#/components/schemas/binary-part-size'
                hash:
                  $ref: '#/components/schemas/binary-part-hash'
                size:
                  $ref: '#/components/schemas/binary-part-size'
              required:
                - expected_binary_size
                - hash
                - size
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary_part:
                    $ref: '#/components/schemas/binary-part'
  /binaries/{binary_prn}/parts:
    get:
      operationId: list-binary-parts
      summary: List binary parts
      tags:
        - Binary Parts
      parameters:
        - name: binary_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary_parts:
                    $ref: '#/components/schemas/array-of-binary-parts'
  /binary_signatures:
    post:
      operationId: create-a-binary-signature
      summary: Create a binary signature
      tags:
        - Binary Signatures
      description: >
        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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                binary_prn:
                  $ref: '#/components/schemas/prn'
                signing_key_prn:
                  $ref: '#/components/schemas/prn'
                signature:
                  $ref: '#/components/schemas/binary-signature-signature'
              required:
                - binary_prn
                - signing_key_prn
                - signature
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  binary_signature:
                    $ref: '#/components/schemas/binary-signature'
  /binary_signatures/{binary_signature_prn}:
    delete:
      operationId: delete-a-binary-signature
      summary: Delete a binary signature
      tags:
        - Binary Signatures
      parameters:
        - name: binary_signature_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: Ok.
  /bundles:
    post:
      operationId: create-a-bundle
      summary: Create a bundle
      tags:
        - Bundles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                artifact_version_prns:
                  $ref: '#/components/schemas/array-of-artifact-version-prns'
                id:
                  $ref: '#/components/schemas/custom-id'
                name:
                  $ref: '#/components/schemas/bundle-name'
              required:
                - artifact_version_prns
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  bundle:
                    $ref: '#/components/schemas/bundle'
    get:
      operationId: list-bundles
      summary: List bundles
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`name`||`:`, `~`, `-`|string|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Bundles
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  bundles:
                    $ref: '#/components/schemas/array-of-bundles'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /bundles/{bundle_prn}:
    get:
      operationId: retrieve-a-bundle
      summary: Retrieve a bundle
      tags:
        - Bundles
      parameters:
        - name: bundle_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  bundle:
                    $ref: '#/components/schemas/bundle'
    patch:
      operationId: update-a-bundle
      summary: Update a bundle
      tags:
        - Bundles
      parameters:
        - name: bundle_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  $ref: '#/components/schemas/bundle-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  bundle:
                    $ref: '#/components/schemas/bundle'
    delete:
      operationId: delete-a-bundle
      summary: Delete a bundle
      tags:
        - Bundles
      parameters:
        - name: bundle_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /ca_certificates:
    post:
      operationId: create-a-ca-certificate
      summary: Create a CA certificate
      tags:
        - CA Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                certificate:
                  description: Base64 encoded CA certificate.
                  type: string
                verification_certificate:
                  description: >
                    Base64 encoded verification certificate.

                    See:
                    [create-a-ca-verification-code](#operation/create-a-ca-verification-code)
                  type: string
                description:
                  type: string
              required:
                - certificate
                - verification_certificate
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  ca_certificate:
                    $ref: '#/components/schemas/ca-certificate'
    get:
      operationId: list-ca-certificates
      summary: List CA certificates
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Operators|Value|
        |-|-|-|
        |`description`|`:`, `~`|string|
        |`inserted_at`|`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`|`:`|string|
        |`updated_at`|`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - CA Certificates
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  ca_certificates:
                    $ref: '#/components/schemas/array-of-ca-certificates'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /ca_certificates/{ca_certificate_prn}:
    delete:
      operationId: delete-a-ca-certificate
      summary: Delete a CA certificate
      tags:
        - CA Certificates
      parameters:
        - name: ca_certificate_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
    get:
      operationId: retrieve-a-ca-certificate
      summary: Retrieve a CA certificate
      tags:
        - CA Certificates
      parameters:
        - name: ca_certificate_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  ca_certificate:
                    $ref: '#/components/schemas/ca-certificate'
    put:
      operationId: update-a-ca-certificate
      summary: Update CA certificate
      tags:
        - CA Certificates
      parameters:
        - name: ca_certificate_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  ca_certificate:
                    $ref: '#/components/schemas/ca-certificate'
  /ca_certificates/verification_codes:
    post:
      operationId: create-a-ca-verification-code
      summary: Create a CA verification code
      tags:
        - CA Certificates
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ca-verification-code'
  /cohorts:
    post:
      operationId: create-a-cohort
      summary: Create a cohort
      tags:
        - Cohorts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  $ref: '#/components/schemas/cohort-description'
                name:
                  $ref: '#/components/schemas/cohort-name'
                product_prn:
                  $ref: '#/components/schemas/prn'
              required:
                - name
                - product_prn
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  cohort:
                    $ref: '#/components/schemas/cohort'
    get:
      operationId: list-cohorts
      summary: List cohorts
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`description`||`:`, `~`|string|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`name`||`:`, `~`|string|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Cohorts
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  cohorts:
                    $ref: '#/components/schemas/array-of-cohorts'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /cohorts/{cohort_prn}:
    get:
      operationId: retrieve-a-cohort
      summary: Retrieve a cohort
      tags:
        - Cohorts
      parameters:
        - name: cohort_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  cohort:
                    $ref: '#/components/schemas/cohort'
    patch:
      operationId: update-a-cohort
      summary: Update a cohort
      tags:
        - Cohorts
      parameters:
        - name: cohort_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  $ref: '#/components/schemas/cohort-description'
                name:
                  $ref: '#/components/schemas/cohort-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  cohort:
                    $ref: '#/components/schemas/cohort'
  /device_certificates:
    post:
      operationId: create-a-device-certificate
      summary: Create a device certificate
      tags:
        - Device Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                device_prn:
                  $ref: '#/components/schemas/device-prn'
                certificate:
                  $ref: '#/components/schemas/device-certificate-pem-base64'
              required:
                - certificate
                - device_prn
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device_certificate:
                    $ref: '#/components/schemas/device-certificate'
    get:
      operationId: list-device-certificates
      summary: List device certificates
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Operators|Value|
        |-|-|-|
        |`device_prn`|`:`|string|
        |`inserted_at`|`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`|`:`|string|
        |`product_prn`|`:`|string|
        |`updated_at`|`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Device Certificates
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device_certificates:
                    $ref: '#/components/schemas/array-of-device-certificates'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /device_certificates/{device_certificate_prn}:
    get:
      operationId: retrieve-a-device-certificate
      summary: Retrieve a device certificate
      tags:
        - Device Certificates
      parameters:
        - name: device_certificate_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-certificate-prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device_certificate:
                    $ref: '#/components/schemas/device-certificate'
    delete:
      operationId: delete-a-device-certificate
      summary: Delete a device certificate
      tags:
        - Device Certificates
      parameters:
        - name: device_certificate_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-certificate-prn'
      responses:
        '204':
          description: No Content.
  /devices:
    post:
      operationId: create-a-device
      summary: Create a device
      tags:
        - Devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                product_prn:
                  $ref: '#/components/schemas/product-prn'
                cohort_prn:
                  $ref: '#/components/schemas/cohort-prn'
                description:
                  $ref: '#/components/schemas/device-description'
                quarantined:
                  $ref: '#/components/schemas/device-quarantined'
                identifier:
                  $ref: '#/components/schemas/device-identifier'
                tags:
                  $ref: '#/components/schemas/array-of-device-tags'
                target:
                  $ref: '#/components/schemas/target-triplet'
              required:
                - identifier
                - product_prn
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device:
                    $ref: '#/components/schemas/device'
    get:
      operationId: list-devices
      summary: List devices
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Operators|Value|
        |-|-|-|
        |`cohort_prn`|`:`|string|
        |`description`|`:`, `~`|string|
        |`identifier`|`:`, `~`|string|
        |`inserted_at`|`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`last_connected_at`|`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`|`:`|string|
        |`product_prn`|`:`|string|
        |`reported_bundle_prn`|`:`|string|
        |`reported_release_prn`|`:`|string|
        |`reported_release_version`|`:`, `~`|string|
        |`target`|`:`, `~`|string|
        |`updated_at`|`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  devices:
                    $ref: '#/components/schemas/array-of-devices'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /devices/{device_prn}:
    get:
      operationId: retrieve-a-device
      summary: Retrieve a device
      tags:
        - Devices
      parameters:
        - name: device_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device:
                    $ref: '#/components/schemas/device'
    patch:
      operationId: update-a-device
      summary: Update a device
      tags:
        - Devices
      parameters:
        - name: device_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                product_prn:
                  $ref: '#/components/schemas/product-prn'
                cohort_prn:
                  $ref: '#/components/schemas/cohort-prn'
                description:
                  $ref: '#/components/schemas/device-description'
                quarantined:
                  $ref: '#/components/schemas/device-quarantined'
                tags:
                  $ref: '#/components/schemas/array-of-device-tags'
                target:
                  $ref: '#/components/schemas/target-triplet'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  device:
                    $ref: '#/components/schemas/device'
    delete:
      operationId: delete-a-device
      summary: Delete a device
      tags:
        - Devices
      parameters:
        - name: device_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /devices/{device_prn}/update:
    post:
      security:
        - api_key_v2: []
      operationId: devices-get-update
      summary: Get device update
      description: >
        Returns information regarding whether an update is available via a
        [release](/peridio-core/reference/bundle-management/releases) or [bundle
        override](/peridio-core/reference/bundle-management/bundle-overrides).
      tags:
        - Devices
      parameters:
        - name: device_prn
          in: path
          required: true
          schema:
            description: The PRN of the device you wish to check for an update for.
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                release_prn:
                  examples:
                    - >-
                      prn:1:a1ed0c4e-f222-4bb3-89dc-48320018875d:release:e4bf3021-b8d7-42d5-a1bd-52121427ebd0
                  description: >-
                    The PRN of the release to consider as the device's current
                    release during bundle resolution.
                  $ref: '#/components/schemas/prn'
                bundle_prn:
                  examples:
                    - >-
                      prn:1:a1ed0c4e-f222-4bb3-89dc-48320018875d:bundle:ddd32c59-fc35-4202-a520-a4eddaa11fb3
                  description: >-
                    The PRN of the bundle to consider as the device's current
                    bundle during bundle resolution.
                  $ref: '#/components/schemas/prn'
                release_version:
                  examples:
                    - 1.0.0
                  description: >-
                    The version to consider as the device's current release
                    version during bundle resolution.
                  $ref: '#/components/schemas/release-version'
                write:
                  description: >-
                    Whether the server's record of what the device's current
                    state is will be updated in reaction to the release PRN,
                    bundle PRN, and release version parameters if they are also
                    supplied.
                  type: boolean
                  default: false
              anyOf:
                - required:
                    - release_prn
                - required:
                    - bundle_prn
                - required:
                    - release_version
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  status:
                    enum:
                      - update
                      - no_update
                      - device_quarantine
                  source_type:
                    enum:
                      - release
                      - bundle_override
                      - null
                    description: >
                      The "source" of the bundle update - from a release, or a
                      bundle override.
                  source_prn:
                    $ref: '#/components/schemas/prn'
                    description: >
                      The "source" prn, could be either a release prn or a
                      bundle override prn
                  bundle_prn:
                    $ref: '#/components/schemas/prn'
                    description: |
                      The bundle associated with `source`.
                  manifest:
                    $ref: '#/components/schemas/manifest'
  /events:
    get:
      operationId: list-events
      summary: List events
      description: >
        List all possible events (Device, Webhooks, API Key, etc.) within the
        specified time range.


        The date range may be adjusted via query parameters.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/event_inserted_at_lt'
        - $ref: '#/components/parameters/event_inserted_at_gte'
        - $ref: '#/components/parameters/event_actor_prn'
        - $ref: '#/components/parameters/event_resource_prn'
        - $ref: '#/components/parameters/event_type'
        - $ref: '#/components/parameters/event_subtype'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  events:
                    $ref: '#/components/schemas/array-of-events'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /products:
    get:
      operationId: list-products
      summary: List products
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`deleted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`name`||`:`, `~`|string|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Products
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
          description: >
            A search query per the [search query
            language](#section/Search-Query-Language).


            Searchable fields:


            |Field|Type|Operations|

            |-|-|-|

            |`archived`|boolean|`:`|

            |`inserted_at`|date-time|`:`, `>`, `>=`, `<`, `<=` |

            |`name`|string|`:`, `~`|

            |`prn`|string|`:`|

            |`updated_at`|date-time|`:`, `>`, `>=`, `<`, `<=` |
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  products:
                    $ref: '#/components/schemas/array-of-products'
                  next_page:
                    $ref: '#/components/schemas/next-page'
    post:
      operationId: create-a-product
      summary: Create a product
      tags:
        - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                archived:
                  $ref: '#/components/schemas/product-archived'
                name:
                  $ref: '#/components/schemas/product-name'
              required:
                - name
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  product:
                    $ref: '#/components/schemas/product'
  /products/{product_prn}:
    get:
      operationId: retrieve-a-product
      summary: Retrieve a product
      tags:
        - Products
      parameters:
        - name: product_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/product'
    patch:
      operationId: update-a-product
      summary: Update a product
      tags:
        - Products
      parameters:
        - name: product_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                archived:
                  $ref: '#/components/schemas/product-archived'
                  description: >
                    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:
                  $ref: '#/components/schemas/product-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/product'
  /releases:
    post:
      operationId: create-a-release
      summary: Create a release
      tags:
        - Releases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                bundle_prn:
                  $ref: '#/components/schemas/prn'
                  description: The bundle the release will distribute to devices.
                phase_mode:
                  $ref: '#/components/schemas/release-phase-mode'
                  default: numeric
                phase_tags:
                  $ref: '#/components/schemas/release-phase-tags'
                phase_value:
                  $ref: '#/components/schemas/release-phase-value'
                cohort_prn:
                  $ref: '#/components/schemas/prn'
                  description: >-
                    The cohort to create the release within, and in turn the
                    cohort it will distribute its bundle to.
                description:
                  $ref: '#/components/schemas/release-description'
                disabled:
                  $ref: '#/components/schemas/release-disabled'
                name:
                  $ref: '#/components/schemas/release-name'
                next_release_prn:
                  $ref: '#/components/schemas/prn'
                  description: >
                    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:
                  $ref: '#/components/schemas/prn'
                  description: >
                    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.
                required:
                  $ref: '#/components/schemas/release-required'
                schedule_date:
                  $ref: '#/components/schemas/release-schedule-availability'
                version:
                  $ref: '#/components/schemas/release-version'
                version-requirement:
                  $ref: '#/components/schemas/release-version-requirement'
              required:
                - bundle_prn
                - cohort_prn
                - name
                - required
                - schedule_date
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  release:
                    $ref: '#/components/schemas/release'
    get:
      operationId: list-releases
      summary: List Releases
      description: |
        **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|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
        |`version_requirement`||`:`, `-`|string|
        |`version`||`:`, `-`|string|
      tags:
        - Releases
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  next_page:
                    $ref: '#/components/schemas/next-page'
                  releases:
                    $ref: '#/components/schemas/array-of-releases'
  /releases/{release_prn}:
    get:
      operationId: retrieve-a-release
      summary: Retrieve a release
      tags:
        - Releases
      parameters:
        - name: release_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  release:
                    $ref: '#/components/schemas/release'
    patch:
      operationId: update-a-release
      summary: Update a release
      tags:
        - Releases
      parameters:
        - name: release_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  $ref: '#/components/schemas/release-description'
                disabled:
                  $ref: '#/components/schemas/release-disabled'
                name:
                  $ref: '#/components/schemas/release-name'
                next_release_prn:
                  $ref: '#/components/schemas/prn'
                  description: >-
                    Update the release's `next_release_prn`. Changes that would
                    result in an invalid [release
                    graph](/peridio-core/reference/device-management/cohorts#release-graph)
                    are rejected.
                phase_mode:
                  $ref: '#/components/schemas/release-phase-mode'
                phase_tags:
                  $ref: '#/components/schemas/release-phase-tags'
                phase_value:
                  $ref: '#/components/schemas/release-phase-value'
                required:
                  $ref: '#/components/schemas/release-required'
                schedule_date:
                  $ref: '#/components/schemas/release-schedule-availability'
                version:
                  $ref: '#/components/schemas/release-version'
                version-requirement:
                  $ref: '#/components/schemas/release-version-requirement'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  release:
                    $ref: '#/components/schemas/release'
    delete:
      operationId: delete-a-release
      summary: Delete a release
      tags:
        - Releases
      parameters:
        - name: release_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /signing_keys:
    post:
      operationId: create-a-signing-key
      summary: Create a signing key
      tags:
        - Signing Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                value:
                  $ref: '#/components/schemas/signing-key-value'
                name:
                  $ref: '#/components/schemas/signing-key-name'
              required:
                - name
                - value
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  signing_key:
                    $ref: '#/components/schemas/signing-key'
    get:
      operationId: list-signing-keys
      summary: List signing keys
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`name`||`:`, `~`|string|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
        |`value`||`:`|string|
      tags:
        - Signing Keys
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  signing_keys:
                    $ref: '#/components/schemas/array-of-signing-keys'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /signing_keys/{signing_key_prn}:
    get:
      operationId: retrieve-a-signing-key
      summary: Retrieve a signing key
      tags:
        - Signing Keys
      parameters:
        - name: signing_key_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  signing_key:
                    $ref: '#/components/schemas/signing-key'
    patch:
      operationId: update-a-signing-key
      summary: Update a signing key
      tags:
        - Signing Keys
      parameters:
        - name: signing_key_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                value:
                  $ref: '#/components/schemas/signing-key-value'
                name:
                  $ref: '#/components/schemas/signing-key-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  signing_key:
                    $ref: '#/components/schemas/signing-key'
    delete:
      operationId: delete-a-signing-key
      summary: Delete a signing key
      tags:
        - Signing Keys
      parameters:
        - name: signing_key_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '204':
          description: No Content.
  /tunnels:
    get:
      operationId: list-tunnels
      summary: List tunnels
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`state`||`:`|string|
        |`device_prn`||`:`|prn|

        `state` can be one of `requested`, `open`, `closed`.
      tags:
        - Tunnels
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                search:
                  $ref: '#/components/schemas/search-with-org'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  tunnels:
                    $ref: '#/components/schemas/array-of-tunnels'
                  next_page:
                    $ref: '#/components/schemas/next-page'
    post:
      operationId: create-a-tunnel
      summary: Create a tunnel
      description: >
        Create a tunnel to a device for remote access.


        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.
      tags:
        - Tunnels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                device_prn:
                  $ref: '#/components/schemas/device-prn'
                  description: |
                    Identifies which device to create a tunnel for.
                device_tunnel_port:
                  $ref: '#/components/schemas/device-tunnel-port'
                cidr_block_allowlist:
                  $ref: '#/components/schemas/cidr-block-allowlist'
                ttl:
                  type: number
                  default: 3600
                  description: >-
                    The amount of time in seconds that the tunnel is available
                    for.
                  minimum: 1
                  maximum: 3600
              required:
                - device_prn
                - device_tunnel_port
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  tunnel:
                    $ref: '#/components/schemas/tunnel'
  /tunnels/{tunnel_prn}:
    get:
      operationId: retrieve-a-tunnel
      summary: Retrieve a tunnel
      tags:
        - Tunnels
      parameters:
        - name: tunnel_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  tunnel:
                    $ref: '#/components/schemas/tunnel'
    patch:
      operationId: update-a-tunnel
      summary: Update a tunnel
      description: |
        Update a tunnel

          - allows changing a tunnel to a closed state.
          - allows extending the expiration (the number of seconds from current time).
      tags:
        - Tunnels
      parameters:
        - name: tunnel_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/tunnel-prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                state:
                  type: string
                  examples:
                    - closed
                  description: >-
                    The state we want the tunnel to be in. Only accepts
                    "closed".
                ttl:
                  type: number
                  description: The amount of time in seconds to extend the tunnel for.
                  minimum: 1
                  maximum: 3600
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/tunnel'
                      - type: object
                        properties:
                          state:
                            examples:
                              - closed
  /users/auth:
    post:
      operationId: authenticate-a-user
      summary: Authenticate a user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                email:
                  $ref: '#/components/schemas/email'
                password:
                  $ref: '#/components/schemas/user-password'
                username:
                  type: string
              anyOf:
                - required:
                    - password
                    - username
                - required:
                    - email
                    - password
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/user-me'
  /users/me:
    get:
      operationId: get-user-me
      summary: Get user me
      tags:
        - Users
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/user-me'
  /web-console-shells:
    post:
      operationId: create-a-web-console-shell
      summary: Create a web console shell
      description: >
        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`
      tags:
        - Web Console
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                device_identifier:
                  $ref: '#/components/schemas/device-identifier'
                  description: |
                    Identifies which device to create a web console shell for.

                    Mutually exclusive with `device_prn`.
                device_prn:
                  $ref: '#/components/schemas/device-prn'
                  description: |
                    Identifies which device to create a web console shell for.

                    Mutually exclusive with `device_identifier`.
                organization_prn:
                  $ref: '#/components/schemas/device-prn'
                  description: >
                    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:
                  type: integer
                  default: 3600
                  description: >-
                    The amount of time in seconds that the URL is valid for.
                    Open connections are closed automatically upon expiration.
                  minimum: 0
                  maximum: 86400
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  expires_at:
                    type: string
                    format: date-time
                    description: When the `url` expires, after which it will be invalid.
                  url:
                    type: string
                    format: uri
                    example: >-
                      https://console.peridio.com/organizations/20301a4f-edca-46ea-89c0-2e92c3dcb0b9/devices/5b615a57-3712-481c-80bb-281f79b1533e/shell/aa63c5e7-d8c7-43e6-a7f5-9f8b63c91ed6
                    description: >-
                      This value is sensitive. Anyone with access to a
                      self-authenticating URL can use it until it has been
                      consumed or expired.
  /webhooks:
    post:
      operationId: create-a-webhook
      summary: Create a webhook
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  $ref: '#/components/schemas/webhook-description'
                url:
                  $ref: '#/components/schemas/webhook-url'
                enabled_events:
                  $ref: '#/components/schemas/webhook-enabled-events'
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    allOf:
                      - $ref: '#/components/schemas/webhook'
                      - type: object
                        properties:
                          secret:
                            $ref: '#/components/schemas/webhook-secret'
    get:
      operationId: list-webhooks
      summary: List webhooks
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Required|Operators|Value|
        |-|-|-|-|
        |`description`||`:`, `~`|string|
        |`inserted_at`||`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`prn`||`:`|string|
        |`updated_at`||`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  webhooks:
                    $ref: '#/components/schemas/array-of-webhooks'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /webhooks/{webhook_prn}:
    get:
      operationId: retrieve-a-webhook
      summary: Retrieve a webhook
      tags:
        - Webhooks
      parameters:
        - name: webhook_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/webhook'
    patch:
      operationId: update-a-webhook
      summary: Update a webhook
      tags:
        - Webhooks
      parameters:
        - name: webhook_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/webhook-prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  $ref: '#/components/schemas/webhook-description'
                url:
                  $ref: '#/components/schemas/webhook-url'
                enabled_events:
                  $ref: '#/components/schemas/webhook-enabled-events'
                state:
                  $ref: '#/components/schemas/webhook-state'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/webhook'
    delete:
      operationId: delete-a-webhook
      summary: Delete a webhook
      tags:
        - Webhooks
      parameters:
        - name: webhook_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/webhook-prn'
      responses:
        '204':
          description: Ok.
  /webhooks/{webhook_prn}/roll_secret:
    post:
      operationId: roll-secret-webhook
      summary: Roll a webhook's secret
      tags:
        - Webhooks
      parameters:
        - name: webhook_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              properties:
                webhook_ttl:
                  $ref: '#/components/schemas/webhook-ttl'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    allOf:
                      - $ref: '#/components/schemas/webhook'
                      - type: object
                        properties:
                          secret:
                            $ref: '#/components/schemas/webhook-secret'
  /webhooks/{webhook_prn}/test_fire:
    post:
      operationId: test-fire-webhook
      summary: Test fire a webhook
      tags:
        - Webhooks
      parameters:
        - name: webhook_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  event:
                    $ref: '#/components/schemas/webhook-test-fire-event'
  /deployments:
    post:
      operationId: create-a-deployment
      summary: Create a deployment
      tags:
        - Deployments v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                conditions:
                  $ref: '#/components/schemas/deployment-conditions'
                  required:
                    - tags
                delta_updatable:
                  $ref: '#/components/schemas/delta-updatable'
                  default: false
                firmware_uuid:
                  $ref: '#/components/schemas/firmware-uuid'
                name:
                  $ref: '#/components/schemas/deployment-name'
                product_prn:
                  $ref: '#/components/schemas/product-prn'
              required:
                - conditions
                - firmware_uuid
                - name
                - product_prn
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  deployment:
                    $ref: '#/components/schemas/deployment'
    get:
      operationId: list-deployments
      summary: List deployments
      description: |
        **Search**

        This resource has the following searchable fields.

        |Key|Operators|Value|
        |-|-|-|
        |`inserted_at`|`:`, `>`, `>=`, `<`, `<=`|date-time|
        |`is_active`|`:`|boolean|
        |`name`|`:`, `~`|string|
        |`prn`|`:`|string|
        |`updated_at`|`:`, `>`, `>=`, `<`, `<=` |date-time|
      tags:
        - Deployments v2
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  deployments:
                    $ref: '#/components/schemas/array-of-deployments'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /deployments/{deployment_prn}:
    get:
      operationId: retrieve-a-deployment
      summary: Retrieve a deployment
      tags:
        - Deployments v2
      parameters:
        - name: deployment_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-prn'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  deployment:
                    $ref: '#/components/schemas/deployment'
    patch:
      operationId: update-a-deployment
      summary: Update a deployment
      description: >
        When updating a deployment, you can modify its `firmware_uuid` only if
        you also pass its associated `product_prn`
      tags:
        - Deployments v2
      parameters:
        - prn: deployment_prn
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-prn'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deployment:
                  type: object
                  properties:
                    name:
                      $ref: '#/components/schemas/deployment-name'
                    conditions:
                      $ref: '#/components/schemas/deployment-conditions'
                    delta_updatable:
                      $ref: '#/components/schemas/delta-updatable'
                    firmware_uuid:
                      $ref: '#/components/schemas/firmware-uuid'
                    is_active:
                      $ref: '#/components/schemas/deployment-is-active'
                    product_prn:
                      $ref: '#/components/schemas/product-prn'
              required:
                - deployment
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  deployment:
                    $ref: '#/components/schemas/deployment'
    delete:
      operationId: delete-a-deployment
      summary: Delete a deployment
      tags:
        - Deployments v2
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: deployment_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-name'
      responses:
        '204':
          description: Ok.
  /firmwares:
    post:
      operationId: create-a-firmware
      summary: Create a firmware
      tags:
        - Firmware v2
      parameters:
        - name: product_prn
          required: true
          schema:
            $ref: '#/components/schemas/prn'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                product_prn:
                  $ref: '#/components/schemas/prn'
                firmware:
                  type: string
                  format: binary
                  description: >-
                    Reference [firmware file
                    requirements](/peridio-core/reference/binary-management/firmware#firmware-file-requirements).
                ttl:
                  type: integer
              required:
                - firmware
                - product_prn
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  firmware:
                    $ref: '#/components/schemas/firmware'
        '422':
          description: Unprocessable Content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    get:
      operationId: list-firmware
      summary: List firmware
      tags:
        - Firmware v2
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/order'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  firmwares:
                    $ref: '#/components/schemas/array-of-firmware'
                  next_page:
                    $ref: '#/components/schemas/next-page'
  /firmwares/{firmware_uuid}:
    delete:
      operationId: delete-a-firmware
      summary: Delete a firmware
      tags:
        - Firmware v2
      parameters:
        - name: firmware_uuid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/firmware-uuid'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                product_prn:
                  $ref: '#/components/schemas/prn'
              required:
                - product_prn
      responses:
        '204':
          description: No Content.
    get:
      operationId: retrieve-a-firmware
      summary: Retrieve a firmware
      description: >
        ### Expandable


        This endpoint has an expandable response. See [expanding
        responses](#section/Expanding-Responses).
      tags:
        - Firmware v2
      parameters:
        - name: firmware_uuid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/firmware-uuid'
        - name: expand
          description: |
            See [expanding responses](#section/Expanding-Responses).

            **Expandable Fields**

            For more information on each field, reference the response.

            - `url`
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                product_prn:
                  $ref: '#/components/schemas/prn'
              required:
                - product_prn
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  firmware:
                    allOf:
                      - $ref: '#/components/schemas/firmware'
                      - type: object
                        properties:
                          url:
                            $ref: '#/components/schemas/firmware-expand-url'
  /orgs/{organization_name}/ca_certificates:
    get:
      operationId: list-ca-certificates
      summary: List CA certificates
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/array-of-ca-certificates'
    post:
      operationId: create-a-ca-certificate
      summary: Create a CA certificate
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                certificate:
                  description: Base64 encoded CA certificate.
                  type: string
                verification_certificate:
                  description: >
                    Base64 encoded verification certificate.

                    See:
                    [create-a-ca-verification-code](#operation/create-a-ca-verification-code)
                  type: string
                description:
                  type: string
              required:
                - certificate
                - verification_certificate
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ca-certificate'
  /orgs/{organization_name}/ca_certificates/{ca_certificate_serial}:
    delete:
      operationId: delete-a-ca-certificate
      summary: Delete a CA certificate
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: ca_certificate_serial
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ca-certificate-serial'
      responses:
        '204':
          description: Ok.
    get:
      operationId: retrieve-a-ca-certificate
      summary: Retrieve a CA certificate
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: ca_certificate_serial
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ca-certificate-serial'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ca-certificate'
    put:
      operationId: update-a-ca-certificate
      summary: Update CA certificate
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: ca_certificate_serial
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ca-certificate-serial'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                jitp:
                  $ref: '#/components/schemas/ca-jitp'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ca-certificate'
  /orgs/{organization_name}/ca_certificates/verification_codes:
    post:
      operationId: create-a-ca-verification-code
      summary: Create a CA verification code
      tags:
        - Legacy CA Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ca-verification-code'
  /orgs/{organization_name}/products/{product_name}/deployments:
    get:
      operationId: list-deployments
      summary: List deployments
      tags:
        - Deployments
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/array-of-deployments'
    post:
      operationId: create-a-deployment
      summary: Create a deployment
      tags:
        - Deployments
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                conditions:
                  $ref: '#/components/schemas/deployment-conditions'
                  required:
                    - tags
                delta_updatable:
                  $ref: '#/components/schemas/delta-updatable'
                  default: false
                firmware:
                  $ref: '#/components/schemas/firmware-uuid'
                is_active:
                  description: Must be `false`.
                  $ref: '#/components/schemas/deployment-is-active'
                name:
                  $ref: '#/components/schemas/deployment-name'
              required:
                - conditions
                - firmware
                - is_active
                - name
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/deployment'
  /orgs/{organization_name}/products/{product_name}/deployments/{deployment_name}:
    delete:
      operationId: delete-a-deployment
      summary: Delete a deployment
      tags:
        - Legacy Deployments
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: deployment_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-name'
      responses:
        '204':
          description: Ok.
    get:
      operationId: retrieve-a-deployment
      summary: Retrieve a deployment
      tags:
        - Legacy Deployments
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: deployment_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/deployment'
    put:
      operationId: update-a-deployment
      summary: Update a deployment
      tags:
        - Legacy Deployments
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: deployment_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deployment:
                  type: object
                  properties:
                    name:
                      $ref: '#/components/schemas/deployment-name'
                    conditions:
                      $ref: '#/components/schemas/deployment-conditions'
                    delta_updatable:
                      $ref: '#/components/schemas/delta-updatable'
                    firmware:
                      $ref: '#/components/schemas/firmware-uuid'
                    is_active:
                      $ref: '#/components/schemas/deployment-is-active'
              required:
                - deployment
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/deployment'
  /orgs/{organization_name}/products/{product_name}/devices:
    get:
      operationId: list-devices
      summary: List devices
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/array-of-devices'
    post:
      operationId: create-a-device
      summary: Create a device
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                cohort_prn:
                  $ref: '#/components/schemas/cohort-prn'
                description:
                  $ref: '#/components/schemas/device-description'
                healthy:
                  $ref: '#/components/schemas/device-healthy'
                identifier:
                  $ref: '#/components/schemas/device-identifier'
                last_communication:
                  description: This field is ignored and has no effect.
                  $ref: '#/components/schemas/device-last-communication'
                tags:
                  $ref: '#/components/schemas/array-of-device-tags'
                target:
                  $ref: '#/components/schemas/target-triplet'
              required:
                - identifier
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/device'
  /orgs/{organization_name}/products/{product_name}/devices/{device_identifier}:
    delete:
      operationId: delete-a-device
      summary: Delete a device
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
      responses:
        '204':
          description: Ok.
    get:
      operationId: retrieve-a-device
      summary: Retrieve a device
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/device'
    put:
      operationId: update-a-device
      summary: Update a device
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                cohort_prn:
                  $ref: '#/components/schemas/cohort-prn'
                description:
                  $ref: '#/components/schemas/device-description'
                healthy:
                  $ref: '#/components/schemas/device-healthy'
                last_communication:
                  description: This field is ignored and has no effect.
                  $ref: '#/components/schemas/device-last-communication'
                tags:
                  $ref: '#/components/schemas/array-of-device-tags'
                target:
                  $ref: '#/components/schemas/target-triplet'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/device'
  /orgs/{organization_name}/products/{product_name}/devices/{device_identifier}/certificates:
    get:
      operationId: list-device-certificates
      summary: List device certificates
      tags:
        - Legacy Device Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/array-of-device-certificates'
    post:
      operationId: create-a-device-certificate
      summary: Create a device certificate
      tags:
        - Legacy Device Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                cert:
                  $ref: '#/components/schemas/device-certificate-pem-base64'
              required:
                - cert
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/device-certificate'
  /orgs/{organization_name}/products/{product_name}/devices/{device_identifier}/certificates/{certificate_serial}:
    get:
      operationId: retrieve-a-device-certificate
      summary: Retrieve a device certificate
      tags:
        - Legacy Device Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
        - name: certificate_serial
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-certificate-serial'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/device-certificate'
    delete:
      operationId: delete-a-device-certificate
      summary: Delete a device certificate
      tags:
        - Legacy Device Certificates
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
        - name: certificate_serial
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-certificate-serial'
      responses:
        '204':
          description: Ok.
  /orgs/{organization_name}/products/{product_name}/devices/{device_identifier}/deployments/{deployment_name}/stats:
    get:
      operationId: retrieve-device-deployment-stats
      summary: Retrieve device deployment stats
      tags:
        - Legacy Devices
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: device_identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/device-identifier'
        - name: deployment_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/deployment-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                    properties:
                      attempts:
                        type: integer
                        example: 5
  /orgs/{organization_name}/products/{product_name}/firmwares:
    get:
      operationId: list-firmware
      summary: List firmware
      tags:
        - Firmware
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/array-of-firmware'
    post:
      operationId: create-a-firmware
      summary: Create a firmware
      tags:
        - Firmware
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                firmware:
                  type: string
                  format: binary
                  description: >-
                    Reference [firmware file
                    requirements](/peridio-core/reference/binary-management/firmware#firmware-file-requirements).
                ttl:
                  type: integer
              required:
                - firmware
      responses:
        '201':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/firmware'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    oneOf:
                      - type: string
                        const: invalid_signature
                      - type: object
                        properties:
                          detail:
                            type: string
                            const: Internal Server Error
  /orgs/{organization_name}/products/{product_name}/firmwares/{firmware_uuid}:
    delete:
      operationId: delete-a-firmware
      summary: Delete a firmware
      tags:
        - Firmware
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: firmware_uuid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/firmware-uuid'
      responses:
        '204':
          description: No Content.
    get:
      operationId: retrieve-a-firmware
      summary: Retrieve a firmware
      description: >
        ### Expandable


        This endpoint has an expandable response. See [expanding
        responses](#section/Expanding-Responses).
      tags:
        - Firmware
      parameters:
        - name: organization_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/organization-name'
        - name: product_name
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/product-name'
        - name: firmware_uuid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/firmware-uuid'
        - name: expand
          description: |
            See [expanding responses](#section/Expanding-Responses).

            **Expandable Fields**

            For more information on each field, reference the response.

            - `url`
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/firmware'
                      - type: object
                        properties:
                          url:
                            $ref: '#/components/schemas/firmware-expand-url'
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: Legacy API Keys. The header value must be `Bearer API_KEY_VALUE`.
    api_key_v2:
      type: apiKey
      name: Authorization
      in: header
      description: API Keys. The header value must be `Bearer API_KEY_VALUE`.
  parameters:
    limit:
      in: query
      name: limit
      description: Specifies the max length of the returned results.
      schema:
        default: 10
        maximum: 100
        minimum: 1
        type: integer
    order:
      in: query
      name: order
      description: >-
        Controls whether the order of results is ascending or descending by
        `inserted_at`.
      schema:
        type: string
        enum:
          - asc
          - desc
    search:
      in: query
      name: search
      description: >
        A search query per the [search query
        language](#section/Search-Query-Language).
      schema:
        type: string
    page:
      in: query
      name: page
      description: >
        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.
      schema:
        type: string
    peridio-signature:
      name: peridio-signature
      in: header
      description: >-
        The webhook signature. See [signature
        verification](/peridio-core/reference/integration-management/webhooks#signature-verification).
      schema:
        type: string
        examples:
          one:
            value: FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF
            summary: One signature.
          two:
            value: >-
              FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51
            summary: Two signatures while secrets are being rolled.
    peridio-published-at:
      name: peridio-published-at
      in: header
      description: >-
        The timestamp of when the event was published (not created). See
        [signature
        verification](/peridio-core/reference/integration-management/webhooks#signature-verification).
      schema:
        type: string
        format: date-time
    event_inserted_at_lt:
      name: inserted_at_lt
      in: query
      description: |
        The ending date point of the range of the query

        Must be greater than event_inserted_at_gte.
      schema:
        type: date-time
    event_inserted_at_gte:
      name: inserted_at_gte
      in: query
      description: |
        The starting date point of the range of the query

        Must be lower than event_inserted_at_lt.
      schema:
        type: date-time
    event_actor_prn:
      name: actor_prn
      in: query
      description: |
        Filter events by actor PRN.
      schema:
        $ref: '#/components/schemas/prn'
    event_resource_prn:
      name: resource_prn
      in: query
      description: |
        Filter events by resource PRN.
      schema:
        $ref: '#/components/schemas/prn'
    event_type:
      name: type
      in: query
      description: |
        Filter events by type.
      schema:
        type: string
        enum:
          - device
          - webhook
          - api_key
    event_subtype:
      name: subtype
      in: query
      description: |
        Filter events by subtype.
      schema:
        type: string
        enum:
          - release_changed
          - claimed_release
          - checked_for_release
          - connected
          - disconnected
          - updated
          - authentication_failed
          - created
          - request_failed
          - test_fire
  schemas:
    api-key-created-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `api-key` event type.
          properties:
            type:
              type: string
              enum:
                - created
            data:
              type: object
              description: Data associated with the `created` subevent type.
              properties:
                api_key_prn:
                  $ref: '#/components/schemas/api-key-prn'
                creator_prn:
                  $ref: '#/components/schemas/user-prn'
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - api_key
        version:
          type: integer
          enum:
            - 1
    api-key-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:api_key:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    array-of-artifacts:
      type: array
      items:
        $ref: '#/components/schemas/artifact'
    array-of-ordered-artifact-versions:
      type: array
      items:
        $ref: '#/components/schemas/artifact-version-item'
    array-of-artifact-versions:
      type: array
      items:
        $ref: '#/components/schemas/artifact-version'
    array-of-artifact-version-prns:
      type: array
      items:
        $ref: '#/components/schemas/prn'
    array-of-binaries:
      type: array
      items:
        $ref: '#/components/schemas/binary'
    array-of-binary-parts:
      type: array
      items:
        $ref: '#/components/schemas/binary-part'
    array-of-bundles:
      type: array
      items:
        $ref: '#/components/schemas/bundle'
    array-of-ca-certificates:
      type: array
      items:
        $ref: '#/components/schemas/ca-certificate'
    array-of-ca-jitp-tags:
      type: array
      items:
        $ref: '#/components/schemas/ca-jitp-tag'
    array-of-cohorts:
      type: array
      items:
        $ref: '#/components/schemas/cohort'
    array-of-deployments:
      type: array
      items:
        $ref: '#/components/schemas/deployment'
    array-of-device-certificates:
      type: array
      items:
        $ref: '#/components/schemas/device-certificate'
    array-of-device-tags:
      type: array
      items:
        $ref: '#/components/schemas/device-tag'
    array-of-devices:
      type: array
      items:
        $ref: '#/components/schemas/device'
    array-of-events:
      type: array
      items:
        $ref: '#/components/schemas/event'
    array-of-firmware:
      type: array
      items:
        $ref: '#/components/schemas/firmware'
    array-of-products:
      type: array
      items:
        $ref: '#/components/schemas/product'
    array-of-releases:
      type: array
      items:
        $ref: '#/components/schemas/release'
    array-of-signatures:
      default: null
      oneOf:
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/signing-signature'
    array-of-signing-keys:
      type: array
      items:
        $ref: '#/components/schemas/signing-key'
    array-of-tunnels:
      type: array
      items:
        $ref: '#/components/schemas/tunnel'
    array-of-webhooks:
      type: array
      items:
        $ref: '#/components/schemas/webhook'
    artifact:
      type: object
      properties:
        custom_metadata:
          oneOf:
            - $ref: '#/components/schemas/custom-metadata-artifact'
            - type: 'null'
        description:
          oneOf:
            - $ref: '#/components/schemas/artifact-description'
            - type: 'null'
        inserted_at:
          type: string
          format: date-time
        name:
          $ref: '#/components/schemas/artifact-name'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        updated_at:
          type: string
          format: date-time
    artifact-description:
      type: string
      minLength: 1
      maxLength: 256
    artifact-name:
      type: string
      minLength: 1
      maxLength: 128
    artifact-version-item:
      type: object
      properties:
        prn:
          $ref: '#/components/schemas/prn'
        index:
          type: integer
    artifact-version:
      type: object
      properties:
        artifact_prn:
          $ref: '#/components/schemas/prn'
        custom_metadata:
          oneOf:
            - $ref: '#/components/schemas/custom-metadata-artifact-version'
            - type: 'null'
        description:
          oneOf:
            - $ref: '#/components/schemas/artifact-version-description'
            - type: 'null'
        inserted_at:
          type: string
          format: date-time
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        version:
          $ref: '#/components/schemas/artifact-version-version'
        updated_at:
          type: string
          format: date-time
    artifact-version-description:
      type: string
      minLength: 1
      maxLength: 256
    artifact-version-version:
      type: string
      minLength: 1
      maxLength: 128
    binary:
      type: object
      properties:
        artifact_version_prn:
          $ref: '#/components/schemas/prn'
        custom_metadata:
          oneOf:
            - $ref: '#/components/schemas/custom-metadata-binary'
            - type: 'null'
        description:
          oneOf:
            - $ref: '#/components/schemas/binary-description'
            - type: 'null'
        hash:
          $ref: '#/components/schemas/binary-hash'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        inserted_at:
          type: string
          format: date-time
        signatures:
          $ref: '#/components/schemas/array-of-signatures'
        size:
          $ref: '#/components/schemas/binary-size'
        state:
          $ref: '#/components/schemas/binary-state'
        target:
          $ref: '#/components/schemas/target-triplet'
        updated_at:
          type: string
          format: date-time
    binary-description:
      type: string
      minLength: 1
      maxLength: 256
    binary-hash:
      description: The lowercase hex encoding of the SHA256 hash of the binary's data.
      type: string
    binary-size:
      description: The expected size in bytes of the binary.
      example: 1800000
      maximum: 53687091200000
      minimum: 0
      type: integer
    binary-state:
      description: The binary state
      type: string
      enum:
        - uploadable
        - hashable
        - hashing
        - signable
        - signed
        - destroyed
    binary-signature-signature:
      type: string
      description: >
        The lowercase hex encoding of the ed25519 signature of the base16
        encoding of the SHA256 hash of the binary.
    binary-signature:
      type: object
      properties:
        binary_prn:
          $ref: '#/components/schemas/prn'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        signature:
          $ref: '#/components/schemas/binary-signature-signature'
        signing_key_prn:
          $ref: '#/components/schemas/prn'
        inserted_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    binary-part:
      type: object
      properties:
        binary_prn:
          $ref: '#/components/schemas/prn'
        hash:
          $ref: '#/components/schemas/binary-part-hash'
        index:
          $ref: '#/components/schemas/binary-part-index'
        inserted_at:
          type: string
          format: date-time
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        size:
          $ref: '#/components/schemas/binary-part-size'
        state:
          $ref: '#/components/schemas/binary-part-state'
        updated_at:
          type: string
          format: date-time
    binary-part-hash:
      description: The lowercase hex encoding of the SHA256 hash of the binary part's data.
      type: string
    binary-part-index:
      description: The binary part index order
      type: integer
    binary-part-size:
      description: The expected size in bytes of the binary part.
      example: 1800000
      maximum: 5368709120
      minimum: 5242880
      type: integer
    binary-part-state:
      description: The binary part state
      type: string
      enum:
        - uploadable
        - invalid_size
        - invalid_hash
        - valid
    bundle:
      type: object
      properties:
        artifact_versions:
          $ref: '#/components/schemas/array-of-ordered-artifact-versions'
        name:
          $ref: '#/components/schemas/bundle-name'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        inserted_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    bundle-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:bundle:c0c25d62-26d4-40b8-b9ab-609936d5d6d0
    bundle-known:
      description: Whether the bundle is known to Peridio or not.
      example: true
      type: boolean
    bundle-name:
      oneOf:
        - type: 'null'
        - type: string
          minLength: 1
          maxLength: 128
    bundle-override-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:bundle_override:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    target-triplet:
      type: string
      minLength: 1
      maxLength: 128
      description: >
        A target triplet string that specifies compaitibility between binaries
        and devices.
      example: arm-linux-androideabi
    ca-certificate:
      type: object
      properties:
        description:
          type: string
        not_after:
          type: string
          format: date-time
        not_before:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/ca-certificate-prn'
        serial:
          $ref: '#/components/schemas/ca-certificate-serial'
    ca-certificate-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:ca_certificate:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    ca-certificate-serial:
      $ref: '#/components/schemas/serial'
    ca-verification-code:
      type: object
      properties:
        verification_code:
          description: Expires in one week
          type: string
    ca-jitp:
      type: object
      properties:
        description:
          type: string
        product_name:
          type: string
        tags:
          $ref: '#/components/schemas/array-of-ca-jitp-tags'
        cohort_prn:
          $ref: '#/components/schemas/prn'
        target:
          type: string
      required:
        - description
        - tags
        - product_name
    ca-jitp-tag:
      type: string
    cidrs:
      type: array
      examples:
        - - 10.0.0.1/16
          - 172.154.0.1/16
      items:
        type: string
    cidr-block-allowlist:
      $ref: '#/components/schemas/cidrs'
      description: |
        A set of CIDR blocks that are allowed to connect to the tunnel.
    cohort:
      type: object
      properties:
        description:
          oneOf:
            - $ref: '#/components/schemas/cohort-description'
            - type: 'null'
        name:
          $ref: '#/components/schemas/cohort-name'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        inserted_at:
          type: string
          format: date-time
        product_prn:
          $ref: '#/components/schemas/prn'
        updated_at:
          type: string
          format: date-time
    cohort-description:
      type: string
      minLength: 1
      maxLength: 256
    cohort-name:
      type: string
      minLength: 1
      maxLength: 128
    cohort-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:cohort:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    custom-metadata:
      type: object
      maxLength: 1000000
    custom-metadata-artifact:
      $ref: '#/components/schemas/custom-metadata'
      description: >
        A JSON object that informs the metadata that will be associated with
        this artifact's binaries when they are included in bundles.


        Max size is 1,000,000 bytes (1 MB).
    custom-metadata-artifact-version:
      $ref: '#/components/schemas/custom-metadata'
      description: >
        A JSON object that informs the metadata that will be associated with
        this artifact version's binaries when they are included in bundles.


        Max size is 1,000,000 bytes (1 MB).
    custom-metadata-binary:
      $ref: '#/components/schemas/custom-metadata'
      description: >
        A JSON object that informs the metadata that will be associated with
        this binary when it is included in bundles.


        Max size is 1,000,000 bytes (1 MB).
    delta-updatable:
      type: boolean
    deployment:
      type: object
      properties:
        conditions:
          $ref: '#/components/schemas/deployment-conditions'
        delta_updatable:
          $ref: '#/components/schemas/delta-updatable'
        firmware_uuid:
          $ref: '#/components/schemas/firmware-uuid'
        is_active:
          $ref: '#/components/schemas/deployment-is-active'
        name:
          $ref: '#/components/schemas/deployment-name'
    deployment-conditions:
      type: object
      properties:
        tags:
          $ref: '#/components/schemas/array-of-device-tags'
        version:
          description: >-
            Reference
            https://hexdocs.pm/elixir/Version.html#module-requirements.
          example: '== 1.0.0'
          type: string
    deployment-is-active:
      type: boolean
      example: false
    deployment-name:
      type: string
    deployment-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:deployment:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    deployment-state:
      enum:
        - 'on'
        - 'off'
    device-tunnel-port:
      type: number
      examples:
        - 22
      description: >-
        The port on which the device is listening for service traffic (e.g.
        ssh).
    event-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499
    event:
      allOf:
        - oneOf:
            - $ref: '#/components/schemas/api-key-created-event'
            - $ref: '#/components/schemas/device-updated-event'
            - $ref: '#/components/schemas/device-connected-event'
            - $ref: '#/components/schemas/device-disconnected-event'
            - $ref: '#/components/schemas/device-release-changed-event'
            - $ref: '#/components/schemas/device-claimed-release-event'
            - $ref: '#/components/schemas/device-checked-for-release-event'
            - $ref: '#/components/schemas/device-authentication-failed-event'
            - $ref: '#/components/schemas/webhook-request-failed-event'
            - $ref: '#/components/schemas/webhook-test-fire-event'
        - type: object
          properties:
            actor_prn:
              $ref: '#/components/schemas/prn'
            resource_prn:
              $ref: '#/components/schemas/prn'
            event_subtype:
              type: string
              enum:
                - release_changed
                - claimed_release
                - checked_for_release
                - connected
                - disconnected
                - updated
                - authentication_failed
                - created
                - request_failed
                - test_fire
    signing-key:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/signing-key-value'
        inserted_at:
          type: string
          format: date-time
        name:
          $ref: '#/components/schemas/artifact-name'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/prn'
        updated_at:
          type: string
          format: date-time
    signing-key-value-pem:
      description: PEM encoded version of the signing key value
      type: string
    signing-key-value:
      type: string
      minLength: 1
      maxLength: 256
    signing-key-name:
      type: string
      minLength: 1
      maxLength: 128
    device:
      type: object
      properties:
        cohort_prn:
          $ref: '#/components/schemas/cohort-prn'
        description:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/device-description'
          example: some description
        identifier:
          $ref: '#/components/schemas/device-identifier'
        inserted_at:
          type: string
          format: date-time
        last_connected_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/device-prn'
        product_prn:
          $ref: '#/components/schemas/product-prn'
        quarantined:
          $ref: '#/components/schemas/device-quarantined'
        reported_bundle_prn:
          $ref: '#/components/schemas/bundle-prn'
        reported_release_prn:
          $ref: '#/components/schemas/release-prn'
        reported_release_version:
          $ref: '#/components/schemas/release-version'
        tags:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/array-of-device-tags'
          example:
            - tag-1
        target:
          oneOf:
            - type: 'null'
            - type: string
          example: arm-linux-androideabi
        updated_at:
          type: string
          format: date-time
    legacy-device:
      type: object
      properties:
        cohort_prn:
          $ref: '#/components/schemas/cohort-prn'
        description:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/device-description'
        firmware_metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/firmware-metadata'
        healthy:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/device-healthy'
        identifier:
          $ref: '#/components/schemas/device-identifier'
        last_communication:
          oneOf:
            - enum:
                - never
            - $ref: '#/components/schemas/device-last-communication'
        prn:
          $ref: '#/components/schemas/device-prn'
        status:
          $ref: '#/components/schemas/device-status'
        tags:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/array-of-device-tags'
        version:
          $ref: '#/components/schemas/device-version'
    device-certificate:
      type: object
      properties:
        not_after:
          type: string
          format: date-time
        not_before:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/device-certificate-prn'
        serial:
          $ref: '#/components/schemas/device-certificate-serial'
    device-certificate-pem-base64:
      description: Base64 encoded device certificate pem.
      type: string
    device-certificate-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:device_certificate:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    device-certificate-serial:
      $ref: '#/components/schemas/serial'
    device-description:
      type: string
      example: some description
    device-healthy:
      type: boolean
    device-quarantined:
      type: boolean
      example: false
    device-identifier:
      description: Uniquely identifies a device within an organization.
      type: string
      example: sn1234
    device-last-communication:
      type: string
      format: date-time
    device-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:device:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    device-status:
      enum:
        - offline
        - online
        - rebooting
        - update pending
        - updating
    device-tag:
      type: string
    device-version:
      oneOf:
        - $ref: '#/components/schemas/version'
        - type: string
          const: unknown
    email:
      type: string
      format: email
    error:
      type: object
      properties:
        code:
          type: string
          description: The type of error
        context:
          type: object
    device-event-cohort:
      oneOf:
        - type: object
          properties:
            cohort_prn:
              $ref: '#/components/schemas/cohort-prn'
            cohort_name:
              $ref: '#/components/schemas/cohort-name'
        - type: 'null'
      description: The cohort of which the device is part of
    device-event-firmware:
      oneOf:
        - type: object
          properties:
            prn:
              $ref: '#/components/schemas/firmware-prn'
            vcs_identifier:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/vcs-identifier'
            version:
              $ref: '#/components/schemas/version'
        - type: 'null'
      description: The firmware associated to the device
    device-event-certificate:
      oneOf:
        - type: object
          properties:
            authority_key_identifier:
              $ref: '#/components/schemas/authority-key-identifier'
            common_name:
              $ref: '#/components/schemas/common-name'
            fingerprint:
              $ref: '#/components/schemas/fingerprint'
        - type: 'null'
    device-event-ca-certificate:
      oneOf:
        - type: object
          properties:
            common_name:
              $ref: '#/components/schemas/common-name'
            fingerprint:
              $ref: '#/components/schemas/fingerprint'
        - type: 'null'
      description: The device's cretificate offered for authentication.
    device-authentication-failed-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              type: string
              enum:
                - authentication_failed
            data:
              type: object
              description: Data associated with the `authentication_failed` subevent type.
              properties:
                reason:
                  type: string
                  enum:
                    - device_is_archived
                    - multi_cert_jitr_disabled
                    - jitp_disabled
                    - jitp_failed
                ip_address:
                  oneOf:
                    - type: string
                      format: ipv4
                    - type: string
                      format: ipv6
                certificate:
                  $ref: '#/components/schemas/device-event-certificate'
                ca_certificate:
                  $ref: '#/components/schemas/device-event-ca-certificate'
                device:
                  type: object
                  description: The device that connected.
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-updated-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              enum:
                - updated
            data:
              description: Data associated with the `updated` subevent type.
              type: object
              properties:
                device:
                  description: The device that was updated.
                  type: object
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
                    description:
                      $ref: '#/components/schemas/device-description'
                    quarantined:
                      $ref: '#/components/schemas/device-quarantined'
                    tags:
                      oneOf:
                        - type: 'null'
                        - $ref: '#/components/schemas/array-of-device-tags'
                    firmware:
                      $ref: '#/components/schemas/device-event-firmware'
                    release:
                      description: The release of the device.
                      oneOf:
                        - type: object
                          properties:
                            prn:
                              $ref: '#/components/schemas/release-prn'
                            version:
                              $ref: '#/components/schemas/release-version'
                        - type: 'null'
                          description: ' '
                    bundle:
                      description: The bundle of the device.
                      oneOf:
                        - type: object
                          properties:
                            prn:
                              $ref: '#/components/schemas/bundle-prn'
                            name:
                              $ref: '#/components/schemas/bundle-name'
                        - type: 'null'
                          description: ' '
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-checked-for-release-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              enum:
                - checked_for_release
            data:
              description: Data associated with the `checked_for_release` subevent type.
              type: object
              properties:
                device:
                  description: The device that checked for a release.
                  type: object
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
                release:
                  description: >-
                    The release the device was told was available to update to,
                    or `null` if no release is available.
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/release-prn'
                        version:
                          $ref: '#/components/schemas/release-version'
                    - type: null
                      description: ' '
                bundle:
                  description: >-
                    The bundle the device was told was available to update to,
                    or `null` if no release or bundle override is available.
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/bundle-prn'
                        name:
                          $ref: '#/components/schemas/bundle-name'
                    - type: null
                      description: ' '
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-claimed-release-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              enum:
                - claimed_release
            data:
              type: object
              description: Data associated with the `claimed_release` subevent type.
              properties:
                device:
                  type: object
                  description: The device that claimed the release.
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
                release:
                  type: object
                  description: The release the device claimed.
                  properties:
                    prn:
                      $ref: '#/components/schemas/release-prn'
                    version:
                      $ref: '#/components/schemas/release-version'
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-connected-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              type: string
              enum:
                - connected
            data:
              type: object
              description: Data associated with the `connected` subevent type.
              properties:
                device:
                  type: object
                  description: The device that connected.
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
                ip_address:
                  oneOf:
                    - type: string
                      format: ipv4
                    - type: string
                      format: ipv6
                certificate:
                  $ref: '#/components/schemas/device-event-certificate'
                ca_certificate:
                  $ref: '#/components/schemas/device-event-ca-certificate'
                route:
                  type: string
                  description: The route, i.e., the URL path to which the device connected.
                headers:
                  description: >
                    Monitored headers that a device supplies during connection
                    will be recorded in this array.


                    Monitored Headers:


                    - `peridio-release-prn`

                    - `peridio-release-version`

                    - `peridio-bundle-prn`

                    - `x-peridio-architecture` (deprecated)

                    - `x-peridio-platform` (deprecated)

                    - `x-peridio-product` (deprecated)

                    - `x-peridio-uuid` (deprecated)

                    - `x-peridio-version` (deprecated)


                    This list can grow, integrations must account for unexpected
                    headers. See [Device API global
                    headers](/device-api#section/Global-Headers).
                  type: object
                  example:
                    peridio-release-prn: >-
                      prn:1:4b8c3b41-f1ce-4c09-83ee-9cb60eb71483:release:d39587b9-4445-4e91-8952-4af83b97fea6
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-disconnected-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              type: string
              enum:
                - disconnected
            data:
              type: object
              description: Data associated with the `disconnected` subevent type.
              properties:
                connected_event_prn:
                  oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/event-prn'
                  description: >-
                    The PRN of the connected event associated with this
                    disconnection, if available.
                device:
                  type: object
                  description: The device that disconnected.
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    device-release-changed-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `device` event type.
          properties:
            type:
              type: string
              enum:
                - release_changed
            data:
              type: object
              description: Data associated with the `release_changed` subevent type.
              properties:
                device:
                  type: object
                  properties:
                    prn:
                      $ref: '#/components/schemas/device-prn'
                    identifier:
                      $ref: '#/components/schemas/device-identifier'
                    cohort:
                      $ref: '#/components/schemas/device-event-cohort'
                from_release:
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/release-prn'
                        version:
                          $ref: '#/components/schemas/release-version'
                    - type: null
                to_release:
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/release-prn'
                        version:
                          $ref: '#/components/schemas/release-version'
                        known:
                          $ref: '#/components/schemas/release-known'
                from_bundle:
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/bundle-prn'
                    - type: null
                to_bundle:
                  oneOf:
                    - type: object
                      properties:
                        prn:
                          $ref: '#/components/schemas/bundle-prn'
                        known:
                          $ref: '#/components/schemas/bundle-known'
                    - type: null
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - device
        version:
          type: integer
          enum:
            - 1
    webhook-request-failed-event:
      type: object
      properties:
        data:
          description: Data associated with the `webhook` event type.
          type: object
          properties:
            type:
              type: string
              enum:
                - request_failed
            data:
              type: object
              description: Data associated with the `request_failed` subevent type.
              properties:
                type:
                  $ref: '#/components/schemas/webhook-request-failed-event-type'
                data:
                  description: Data associated with the subevent.
                  oneOf:
                    - $ref: >-
                        #/components/schemas/webhook-request-failed-host-resolution-failed-event
                    - $ref: >-
                        #/components/schemas/webhook-request-failed-response-timeout-event
                    - $ref: >-
                        #/components/schemas/webhook-request-failed-response-status-event
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - webhook
        version:
          type: integer
          enum:
            - 1
    webhook-test-fire-event:
      type: object
      properties:
        data:
          type: object
          description: Data associated with the `webhook` event type.
          properties:
            type:
              enum:
                - test_fire
            data:
              type: object
              description: Data associated with the `test_fire` subevent type.
              properties:
                webhook_prn:
                  $ref: '#/components/schemas/webhook-prn'
        inserted_at:
          type: string
          format: date-time
        prn:
          $ref: '#/components/schemas/event-prn'
        type:
          type: string
          enum:
            - webhook
        version:
          type: integer
          enum:
            - 1
    event-type:
      type: string
      enum:
        - device
        - webhook
    device-event-type:
      type: string
      enum:
        - checked_for_release
        - claimed_release
        - connected
        - disconnected
        - release_changed
    authority-key-identifier:
      type: string
      description: The authority key identifier of the certificate.
      minLength: 1
      maxLength: 256
    common-name:
      type: string
      description: The common name of the certificate.
      minLength: 1
      maxLength: 64
    fingerprint:
      type: string
      description: The upcased hex encoding of the SHA-256 fingerprint of the certificate.
      minLength: 64
      maxLength: 64
    webhook-event-type:
      type: string
      enum:
        - request_failed
        - test_fire
    webhook-request-failed-host-resolution-failed-event:
      type: object
      properties:
        webhook:
          type: object
          properties:
            prn:
              $ref: '#/components/schemas/webhook-prn'
    webhook-request-failed-response-timeout-event:
      type: object
      properties:
        webhook:
          type: object
          properties:
            prn:
              $ref: '#/components/schemas/webhook-prn'
    webhook-request-failed-response-status-event:
      type: object
      properties:
        webhook:
          type: object
          properties:
            prn:
              $ref: '#/components/schemas/webhook-prn'
        status:
          type: integer
    webhook-request-failed-event-type:
      type: string
      enum:
        - host_resolution_failed
        - response_timeout
        - response_status
    firmware:
      type: object
      properties:
        architecture:
          $ref: '#/components/schemas/product-architecture'
        author:
          $ref: '#/components/schemas/firmware-author'
        inserted_at:
          type: string
          format: date-time
        platform:
          $ref: '#/components/schemas/platform'
        product:
          $ref: '#/components/schemas/product-name'
        updated_at:
          type: string
          format: date-time
        uuid:
          $ref: '#/components/schemas/firmware-uuid'
        vcs_identifier:
          $ref: '#/components/schemas/vcs-identifier'
        version:
          $ref: '#/components/schemas/version'
    firmware-author:
      type: string
    firmware-metadata:
      type: object
      properties:
        architecture:
          $ref: '#/components/schemas/product-architecture'
        author:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/firmware-author'
        description:
          oneOf:
            - type: 'null'
            - type: string
        fwup_version:
          oneOf:
            - type: 'null'
            - type: string
          description: The version of FWUP bundled within the firmware.
        misc:
          oneOf:
            - type: 'null'
            - type: string
        platform:
          $ref: '#/components/schemas/platform'
        product:
          $ref: '#/components/schemas/product-name'
        uuid:
          $ref: '#/components/schemas/firmware-uuid'
        vcs_identifier:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/vcs-identifier'
        version:
          $ref: '#/components/schemas/version'
    firmware-uuid:
      type: string
      format: uuid
      description: Uniquely identifies a firmware.
    firmware-expand-url:
      type: string
      format: url
      description: >
        Expand required. See [expanding
        responses](#section/Expanding-Responses).


        Presigned download url.
    firmware-prn:
      $ref: '#/components/schemas/prn'
      example: >-
        prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:firmware:e0040f63-4e1c-43e7-880a-d6986a35c499
    key:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/key-key'
        name:
          $ref: '#/components/schemas/key-name'
    key-key:
      type: string
    key-name:
      type: string
    next-page:
      type: string
    organization-name:
      type: string
    platform:
      type: string
    custom-id:
      description: >
        A user provided custom UUID id for the resource database record. This
        overrides peridio's autogenerated ID for

        the user provided one.


        Use with caution.
      type: string
    prn:
      description: >
        [Peridio Resource
        Names](/peridio-core/reference/account-management/peridio-resource-names)
        (PRNs) uniquely identify Peridio resources.
      type: string
    product:
      type: object
      properties:
        archived:
          $ref: '#/components/schemas/product-archived'
        inserted_at:
          type: string
          format: date-time
        name:
          $ref: '#/components/schemas/product-name'
        prn:
          $ref: '#/components/schemas/prn'
        updated_at:
          type: string
          format: date-time
    product-architecture:
      type: string
    product-archived:
      type: boolean
      default: false
    product-name:
      type: string
      description: Uniquely identifies a product within an organization.
    product-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:product:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    release:
      type: object
      properties:
        bundle_prn:
          $ref: '#/components/schemas/prn'
        cohort_prn:
          $ref: '#/components/schemas/prn'
        description:
          $ref: '#/components/schemas/release-description'
        disabled:
          $ref: '#/components/schemas/release-disabled'
        name:
          $ref: '#/components/schemas/release-name'
        next_release_prn:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/prn'
        organization_prn:
          $ref: '#/components/schemas/prn'
        phase_mode:
          $ref: '#/components/schemas/release-phase-mode'
        phase_tags:
          $ref: '#/components/schemas/release-phase-tags'
        phase_type:
          $ref: '#/components/schemas/release-phase-type'
        phase_value:
          $ref: '#/components/schemas/release-phase-value'
        required:
          $ref: '#/components/schemas/release-required'
        schedule_date:
          $ref: '#/components/schemas/release-schedule-availability'
        schedule_complete:
          $ref: '#/components/schemas/release-schedule-complete'
        prn:
          $ref: '#/components/schemas/prn'
        inserted_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        version:
          $ref: '#/components/schemas/release-version'
        version_requirement:
          $ref: '#/components/schemas/release-version-requirement'
    release-disabled:
      description: >
        If a release is marked as disabled it cannot be resolved during release
        resolution.
      type: boolean
    release-phase-mode:
      description: >
        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.
      type: string
      enum:
        - tags
        - numeric
    release-phase-tags:
      description: >
        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.
      $ref: '#/components/schemas/array-of-device-tags'
    release-phase-value:
      description: >
        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`.
      type: number
      minimum: 0
      maximum: 1000000000
    release-phase-type:
      type: string
      enum:
        - static
        - percent
    release-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:release:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    release-description:
      default: null
      oneOf:
        - type: string
        - type: 'null'
    release-name:
      type: string
    release-required:
      type: boolean
      description: >
        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).
    release-schedule-availability:
      type: string
      format: date-time
      description: >-
        Before this date-time, the release will not be resolvable when checking
        for updates. You may use this to schedule a future release.
    release-schedule-complete:
      type: boolean
    release-version:
      description: >-
        The release version. If provided, it has to be a valid
        [version](https://hexdocs.pm/elixir/Version.html#content). Used in
        [dynamic release
        resolution](/peridio-core/reference/bundle-management/releases#dynamic-resolution).
      example: 1.0.0
      type: string
    release-known:
      description: Whether the release is known to Peridio or not.
      example: true
      type: boolean
    release-version-requirement:
      description: >-
        The release version requirement. If provided, it has to be a valid
        [requirement](https://hexdocs.pm/elixir/Version.html#module-requirements).
        Used in [dynamic release
        resolution](/peridio-core/reference/bundle-management/releases#dynamic-resolution).
      example: '== 1.0.0'
      type: string
    role-name:
      enum:
        - admin
        - read
        - read
        - write
    search-with-org:
      type: string
      description: |
        The `organization_prn` is required as part of the search.
      example: organization_prn:'prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef'
    serial:
      type: string
      example: '522154175989108335861639249273408275957749326848'
    signing-signature:
      type: object
      properties:
        signature:
          $ref: '#/components/schemas/binary-signature-signature'
        signing_key_prn:
          $ref: '#/components/schemas/prn'
        public_value:
          $ref: '#/components/schemas/signing-key-value-pem'
    manifest:
      description: >
        The manifest associated with `bundle`. Includes metadata about the
        binaries available to download, including a presigned download URL.
      type: array
      items:
        type: object
        properties:
          artifact_prn:
            $ref: '#/components/schemas/prn'
            description: |
              The artifact prn associated with `artifact_version_prn`.
          artifact_version:
            $ref: '#/components/schemas/prn'
            description: |
              The artifact version associated with `binary_prn`.
          binary_prn:
            $ref: '#/components/schemas/prn'
          custom_metadata:
            $ref: '#/components/schemas/custom-metadata'
            description: >
              A JSON object that device's may use to inform decisions regarding
              last mile application of the binary including: downloading,
              persisting, installing, and custom use cases.


              Max size is 1,000,000 bytes (1 MB).
          hash:
            $ref: '#/components/schemas/binary-hash'
          signatures:
            default: null
            oneOf:
              - type: 'null'
              - type: array
                items:
                  type: object
                  properties:
                    signature:
                      $ref: '#/components/schemas/binary-signature-signature'
                    signing_key_prn:
                      $ref: '#/components/schemas/prn'
          size:
            $ref: '#/components/schemas/binary-size'
          target:
            $ref: '#/components/schemas/target-triplet'
          url:
            type: string
    tunnel:
      type: object
      properties:
        cidr_block_allowlist:
          $ref: '#/components/schemas/cidr-block-allowlist'
        device_proxy_ip_address:
          type: string
          examples:
            - 10.0.1.1
          description: The wireguard interface IP address for the device.
          nullable: true
        device_proxy_port:
          type: number
          examples:
            - 47539
          description: The port on which the device is listening for wireguard UDP traffic.
          nullable: true
        device_public_key:
          type: string
          description: The device's public key for wireguard.
          examples:
            - Y4nCIXdpb+f3WgPi0377FDPCAfP+st82s98lTRepHEk=
          nullable: true
        device_tunnel_port:
          $ref: '#/components/schemas/device-tunnel-port'
        server_proxy_ip_address:
          type: string
          examples:
            - 10.0.0.1
          description: The wireguard peer IP address for the Peridio proxy server.
          nullable: true
        server_proxy_port:
          type: number
          examples:
            - 49293
          description: The port on which the server is listening for wireguard UDP traffic.
          nullable: true
        server_public_key:
          type: string
          description: The Peridio proxy server public key for wireguard.
          examples:
            - 2+h9vwIwg/1zTW9XLFzUmiTwCRRq7mzLgDnZfWEislY=
          nullable: true
        server_tunnel_ip_address:
          type: string
          examples:
            - 3.82.23.99
          description: >-
            The IP address of the Peridio proxy server through which traffic
            will be routed. Both the device and the accessor will use this IP
            address.
        server_tunnel_port:
          type: number
          examples:
            - 47532
          description: >-
            The port of the Peridio proxy server through which traffic will be
            routed.
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: >-
            The point in time at which the tunnel's TTL will expire and the
            tunnel will automatically move to the `closed` state.
        state:
          enum:
            - requested
            - open
            - closed
        device_prn:
          $ref: '#/components/schemas/device-prn'
        organization_prn:
          $ref: '#/components/schemas/prn'
        prn:
          $ref: '#/components/schemas/tunnel-prn'
        inserted_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    tunnel-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:tunnel:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    user-me:
      allOf:
        - type: object
          properties:
            email:
              $ref: '#/components/schemas/email'
            username:
              type: string
    user-password:
      type: string
    user-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: prn:1:user:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    user-username:
      type: string
    vcs-identifier:
      example: d670460b4b4aece5915caf5c68d12f560a9fe3e4
      type: string
    version:
      description: Reference https://hexdocs.pm/elixir/Version.html#module-versions.
      example: 1.0.0-alpha.3
      type: string
    webhook:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/webhook-state'
        inserted_at:
          type: string
          format: date-time
        url:
          $ref: '#/components/schemas/webhook-url'
        description:
          $ref: '#/components/schemas/webhook-description'
        enabled_events:
          $ref: '#/components/schemas/webhook-enabled-events'
        prn:
          $ref: '#/components/schemas/webhook-prn'
        updated_at:
          type: string
          format: date-time
    webhook-description:
      type: string
    webhook-secret:
      type: string
      example: C4FE345F29EF6156BD40B6DF73625243
      description: The secret used to create and verify webhook signatures.
    webhook-url:
      type: string
    webhook-state:
      enum:
        - enabled
        - disabled
    webhook-enabled-events:
      type: array
      items:
        enum:
          - device.release_changed
          - webhook.test_fire
    webhook-prn:
      allOf:
        - $ref: '#/components/schemas/prn'
        - example: >-
            prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:webhook:b3f1f699-3bc8-4c77-bda2-b974595d5e3f
    webhook-ttl:
      type: integer
      default: 0
      description: >-
        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](/peridio-core/reference/integration-management/webhooks).
webhooks:
  api_key_created:
    post:
      security: []
      summary: Created
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when an api key is created.
      operationId: api-key-created
      tags:
        - API Key Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api-key-created-event'
      responses:
        '200':
          description: Ok.
  device_checked_for_release:
    post:
      security: []
      summary: Checked for release
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when a device checks for an update with
        [get-update](/device-api#devices/operation/get-update).
      operationId: device-checked-for-release
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-checked-for-release-event'
      responses:
        '200':
          description: Ok.
  device_claimed_release:
    post:
      security: []
      summary: Claimed release
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when a device claims access to a phased release
        during a [get-update](/device-api#devices/operation/get-update).
      operationId: device-claimed-release
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-claimed-release-event'
      responses:
        '200':
          description: Ok.
  device_connected:
    post:
      security: []
      summary: Connected
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        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.
      operationId: device-connected
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-connected-event'
      responses:
        '200':
          description: Ok.
  device_disconnected:
    post:
      security: []
      summary: Disconnected
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when a device disconnects from the device
        websocket.
      operationId: device-disconnected
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-disconnected-event'
      responses:
        '200':
          description: Ok.
  device_release_changed:
    post:
      security: []
      summary: Release changed
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when a device informs Peridio of its current
        release or bundle via the `peridio-release-prn` or `peridio-bundle-prn`
        headers, and that release or bundle is different than the one Peridio
        currently had on record. In cases where a `peridio-bundle-prn` header is
        supplied, the `to_release` property will be `null`.


        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 along with the new release's bundle.
        Similarly, if Peridio thought the device was on bundle 1, but then the
        device informed Peridio it was on bundle 2, then this event would be
        created going from bundle 1 to 2, with a `to_release` of `null`.
      operationId: device-release-changed
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-release-changed-event'
      responses:
        '200':
          description: Ok.
  device_updated:
    post:
      security: []
      summary: Updated
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when a device database record is updated.
      operationId: device-updated
      tags:
        - Device Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/device-updated-event'
      responses:
        '200':
          description: Ok.
  webhook_request_failed:
    post:
      security: []
      summary: Request failed
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created when an attempt to publish an event via a webhook
        fails.
      operationId: webhook-request-failed
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-request-failed-event'
      responses:
        '200':
          description: Ok.
  webhook_test_fire:
    post:
      security: []
      summary: Test fire
      description: >
        See the [webhooks
        reference](/peridio-core/reference/integration-management/webhooks#supported-events)
        for a list of supported events.


        This event is created by the Peridio API
        [test-fire-webhook](/admin-api#webhooks/operation/test-fire-webhook)
        endpoint as well as during [URL
        verification](/peridio-core/reference/integration-management/webhooks#url-verification).
      operationId: webhook-test-fire
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/peridio-signature'
        - $ref: '#/components/parameters/peridio-published-at'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook-test-fire-event'
      responses:
        '200':
          description: Ok.