openapi: 3.0.1
info:
  title: plgd HTTP Gateway
  version: 2.7.19
servers:
  - url: "https://try.plgd.cloud"
paths:
  "/.well-known/configuration":
    get:
      tags:
        - "Configuration"
      summary: "plgd hub clients configuration"
      description: |
        Basic publicly available configuration required to connect the device to the plgd hub.
      responses:
        200:
          description: Configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HubConfiguration"
  "/api/v1/things":
    get:
      tags:
        - "Web of Things"
      summary: "Retrieve Hub Thing Description"
      description: |
        Retrieve the description of the PLGD hub, including links to all associated things.
      responses:
        200:
          description: "Thing description of the plgd hub."
          content:
            application/json:
              schema:
                $ref: "https://raw.githubusercontent.com/plgd-dev/hub/main/http-gateway/swagger.wot.yaml#/components/schemas/thing"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/things/{deviceId}":
    get:
      tags:
        - "Web of Things"
      summary: "Retrieve Device Thing Description"
      description: |
        Retrieve the thing description for a specific device. The device must be listed in the links of /api/v1/things.
      parameters:
        - $ref: "#/components/parameters/deviceId"
      responses:
        200:
          description: "Thing description of the device."
          content:
            application/json:
              schema:
                $ref: "https://raw.githubusercontent.com/plgd-dev/hub/main/http-gateway/swagger.wot.yaml#/components/schemas/thing"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices":
    get:
      tags:
        - "Devices"
      summary: "Get all devices"
      description: |
        All registered devices user is authorized to use are returned in form of a stream, chunk by chunk. Attach your reader and consume device by device. Various filters allows you to be more concrete in devices you would like to get. Error response might be returned immediately, but also anytime during the stream reading.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/statusFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "Stream of devices or errors."
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: "#/components/schemas/Device"
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
    delete:
      tags:
        - "Devices"
      summary: "Delete devices"
      description: |
        Request to delete selected or all devices.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "List of deleted device IDs"
          content:
            application/json:
              schema:
                type: object
                properties:
                  deviceIds:
                    type: array
                    items:
                      type: string
                    example:
                      - "7aaa3d7d-b8e2-4a83-5ce3-4d81ad2bf5f8"
                      - "3eeac884-f38c-48dc-714f-0f36a829cb89"
        204:
          $ref: "#/components/responses/accepted"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/devices/{deviceId}":
    get:
      tags:
        - "Devices"
      summary: "Get device by ID"
      description: |
        Get information about a single device. Alternative is to call 'Get all devices' with a `deviceId` filter query parameter.
      parameters:
        - $ref: "#/components/parameters/deviceId"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "Information about a single device."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        404:
          $ref: "#/components/responses/notFound"
    delete:
      tags:
        - "Devices"
      summary: "Delete device by ID"
      description: |
        Delete a single device by ID. Alternative is to call 'Delete devices' with a `deviceIdFilter` filter query parameter.
      parameters:
        - $ref: "#/components/parameters/deviceId"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "List of deleted device IDs"
          content:
            application/json:
              schema:
                type: object
                properties:
                  deviceIds:
                    type: array
                    items:
                      type: string
                    example:
                      - "7aaa3d7d-b8e2-4a83-5ce3-4d81ad2bf5f8"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/resource-links":
    get:
      tags:
        - "Resource Links"
      summary: "Get resource links"
      description: |
        Each device publishes links to its resources to the plgd hub. Authorized user can get all published links in form of a stream, chunk by chunk. Attach your reader and consume link by link. Various filters allows you to be more concrete in links you would like to get. Error response might be returned immediately, but also anytime during the stream reading.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
        - $ref: "#/components/parameters/typeFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "Stream of resource links or errors."
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: "#/components/schemas/ResourceLinks"
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/resource-links":
    get:
      tags:
        - "Resource Links"
      summary: "Get device's resource links"
      description: |
        Get resource links published by a single device. Alternative is to call 'Get all resource links' with `deviceId` filter query parameter.
      parameters:
        - $ref: "#/components/parameters/deviceId"
        - $ref: "#/components/parameters/typeFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "Resource links of a single device."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceLinks"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/devices/{deviceId}/resource-links/{resourceHref}":
    parameters:
      - $ref: "#/components/parameters/deviceId"
      - $ref: "#/components/parameters/resourceHref"
    post:
      tags:
        - "Resource Links"
      summary: "Create a resource"
      description: |
        This API enables you to create a new resource on a collection supporting create operation - interface `oic.if.create` shall be present. The resource is automatically published by the device, about what you are informed through an `RESOURCE_PUBLISHED` event.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/timeToLive"
      requestBody:
        description: "Create request as defined by the Open Connectivity Foundation."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceCreateContent"
        required: true
      responses:
        200:
          description: "Resource create response containing href to a new resource."
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Resource"
              example:
                data:
                  resourceId:
                    href: "/switches"
                    deviceId: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
                  content:
                    href: "/switches/1"
                    rt:
                      - "oic.r.switch.binary"
                    if:
                      - "oic.if.a"
                      - "oic.if.baseline"
                    rep:
                      value: false
                  auditContext:
                    userId: "9772fcff-dcfb-4db8-a6c9-1b75f2165eb1"
                    correlationId: "e20f1eef-2eeb-4755-b33e-139106d28e2c"
                  eventMetadata:
                    connectionId: "194.1.25.111:61692"
                    sequence: "7"
                    version: "0"
                    timestamp: "1625427236429144178"
                  status: "CREATED"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/notFound"
    delete:
      tags:
        - "Resource Links"
      summary: "Delete a resource"
      description: |
        Request to delete a resource is an async operation. The device after successful resource deletion unpublishes the resource from the plgd hub. This information is published to the WebSocket in form of an `RESOURCE_UNPUBLISHED` event.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/timeToLive"
      responses:
        200:
          description: "Confirmation event about successful resource deletion."
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Resource"
        204:
          $ref: "#/components/responses/accepted"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/resources":
    get:
      tags:
        - "Resources"
      summary: "Get all resources"
      description: |
        The plgd hub builds an up to date [Twin](https%3A%2F%2Fplgd.dev%2Ffeatures%2Fdevice-shadow%2F) for each published resource. This API allows you to retrieve shadow contents of all resources published by all device. Response is sent in form of a stream, chunk by chunk. Error response might be returned immediately, but also anytime during the stream reading.
        If you specify a `resourceIdFilter` that also contains an `etag`, then the response for an unmodified resource will include `data.status = NOT_MODIFIED` without `data.content.data`.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/resourceIdFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          description: "Stream of resource shadow contents or errors."
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      types:
                        type: array
                        items:
                          type: string
                        example:
                          - "oic.r.switch.binary"
                      data:
                        $ref: "#/components/schemas/Resource"
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/resources/":
    get:
      tags:
        - "Resources"
      summary: "Retrieve device's resources"
      description: |
        The plgd hub builds an up to date [Twin](https%3A%2F%2Fplgd.dev%2Ffeatures%2Fdevice-shadow%2F) for each published resource. This API allows you to retrieve shadow contents of all resources published by this device. Response is sent in form of a stream, chunk by chunk. Error response might be returned immediately, but also anytime during the stream reading.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/deviceId"
        - $ref: "#/components/parameters/typeFilter"
      responses:
        200:
          description: "Stream of resource shadow contents or errors."
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      types:
                        type: array
                        items:
                          type: string
                        example:
                          - "oic.r.switch.binary"
                      data:
                        $ref: "#/components/schemas/Resource"
                  error:
                    $ref: "#/components/schemas/Error"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/resources/{resourceHref}":
    parameters:
      - $ref: "#/components/parameters/deviceId"
      - $ref: "#/components/parameters/resourceHref"
    get:
      tags:
        - "Resources"
      summary: "Retrieve a resource"
      description: |
        The plgd hub builds an up to date [Twin](https%3A%2F%2Fplgd.dev%2Ffeatures%2Fdevice-shadow%2F) for each published resource.
        Retrieving it's content using this API returnes an eventually consistent shadow content of the resource.
        There is a possibility to bypass the shadow by setting the query parameter `shadow` to `false` or by setting the interface query parameter, which allows you to set the command expiration.
        If etag is provided, the response will be 304 Not Modified if the resource has not changed otherwise the resource will be returned.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/interface"
        - $ref: "#/components/parameters/shadow"
        - $ref: "#/components/parameters/timeToLive"
        - $ref: "#/components/parameters/etag"
        - $ref: "#/components/parameters/onlyContent"
      responses:
        200:
          description: "Resource content."
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Resource"
        304:
          description: "Resource content not modified."
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        404:
          $ref: "#/components/responses/notFound"
    put:
      tags:
        - "Resources"
      summary: "Update a resource"
      description: |
        Resource update request is send directly to the device, carrying values which should be modified. Update confirmation doesn't have to carry updated content, this is up to the device implementation if it replies with an up to date values. If subscribed to the websocket, after the update command is successfully accepted by the device, event `RESOURCE_UPDATED` with matching `correlationId` is emitted. At the moment values are applied / changed on the device (e.g. resource update might trigger some processing, which was successfully requested but operation is in progress) event `RESOURCE_CHANGED` is emitted and resource shadow updated.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/interface"
        - $ref: "#/components/parameters/timeToLive"
        - $ref: "#/components/parameters/onlyContent"
      requestBody:
        description: "Updated content of the resource."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceContent"
        required: true
      responses:
        200:
          description: "Confirmation of an update. Presence of the content in the response depends on the device implementation."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceContent"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/devices/{deviceId}/metadata":
    put:
      tags:
        - "Devices"
      summary: "Update device metadata"
      description: |
        Device metadata represent configuration of the relationship between the plgd hub and the device. It's not configuration of the device itself. [Twin](https%3A%2F%2Fplgd.dev%2Ffeatures%2Fdevice-shadow%2F) configuration is part of the metadata. By setting this value you control if the shadow for this device is kept up to date or not.
      security:
        - oauth2:
            - "plgd.devices"
      parameters:
        - $ref: "#/components/parameters/deviceId"
        - $ref: "#/components/parameters/timeToLive"
      requestBody:
        description: "Device metadata change successfully requested. If the device is online, change is immediately applied. If the device is offline, pending command is registered and executed at the moment device comes online."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceMetadata"
            example:
              twinEnabled: false
        required: true
      responses:
        200:
          description: "Metadata successfully updated."
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        404:
          $ref: "#/components/responses/notFound"
  "/api/v1/pending-commands":
    get:
      tags:
        - "Pending Commands"
      summary: "Get all pending commands"
      description: |
        Resource shadow can be updated even if the device is offline. Each update request creates a pending command which is executed at the moment devices comes online. If the device is offline, this API allows you to retrieve all pending commands in form of a stream. Various filters allows you to be more concrete in pending commands you would like to get. Error response might be returned immediately, but also anytime during the stream reading.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/resourceIdFilter"
        - $ref: "#/components/parameters/commandFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/pendingCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/pending-commands":
    parameters:
      - $ref: "#/components/parameters/deviceId"
    get:
      tags:
        - "Pending Commands"
      summary: "Get all resource's pending commands for a device"
      description: |
        Retrieve all resource's pending commands for a single device. Alternative is to call 'Get all pending commands' with `deviceIdFilter` and `commandFilter` query parameters.
      parameters:
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/resourceCommandFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/pendingCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/pending-metadata-updates":
    parameters:
      - $ref: "#/components/parameters/deviceId"
    get:
      tags:
        - "Pending Commands"
      summary: "Get all pending metadata updates for a device"
      description: |
        Retrieve all pending metadata updates for a single device. Alternative is to call 'Get all pending commands' with `deviceIdFilter` and `commandFilter` query parameters.
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/pendingCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
    delete:
      tags:
        - "Pending Commands"
      summary: "Cancel pending metadata update."
      description: |
        Pending metadata update is identified by the correlationId. If a `correlationIdFilter` is not specified, all pending metadata updates will be canceled.
      parameters:
        - $ref: "#/components/parameters/correlationIdFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/canceledCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/resources/{resourceHref}/pending-commands":
    parameters:
      - $ref: "#/components/parameters/deviceId"
      - $ref: "#/components/parameters/resourceHref"
    get:
      tags:
        - "Pending Commands"
      summary: "Get all pending commands for a resource."
      description: |
        Retrieve all pending commands for a single resource. Alternative is to call 'Get all pending commands' with `resourceIdFilter` and `commandFilter` query parameters.
      parameters:
        - $ref: "#/components/parameters/typeFilter"
        - $ref: "#/components/parameters/resourceCommandFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/pendingCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
    delete:
      tags:
        - "Pending Commands"
      summary: "Cancel pending command."
      description: |
        Pending command is identified by the correlationId. If a `correlationIdFilter` is not specified, all pending commands will be canceled.
      parameters:
        - $ref: "#/components/parameters/correlationIdFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/canceledCommands"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/events":
    get:
      tags:
        - "Resource Events"
      summary: "Get resource events"
      description: |
        All events from resources belonging to devices user is authorized to use are returned in form of a stream, chunk by chunk. Attach your reader and consume event by event. Filters allow you to select devices and resources of interest, and the timestamp filter allows to filter out events and return only those that occurred after a given time. Error response might be returned immediately, but also anytime during the stream reading.
      parameters:
        - $ref: "#/components/parameters/deviceIdFilter"
        - $ref: "#/components/parameters/resourceIdFilter"
        - $ref: "#/components/parameters/timestampFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/events"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/events":
    parameters:
      - $ref: "#/components/parameters/deviceId"
    get:
      tags:
        - "Resource Events"
      summary: "Get resource events from selected device"
      description: |
        Get all resource events that occurred on the device with given `deviceId`. Alternative is to call 'Get resource events' with `deviceIdFilter` query parameter.
      parameters:
        - $ref: "#/components/parameters/timestampFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/events"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/devices/{deviceId}/resources/{resourceHref}/events":
    parameters:
      - $ref: "#/components/parameters/deviceId"
      - $ref: "#/components/parameters/resourceHref"
    get:
      tags:
        - "Resource Events"
      summary: "Get events from selected resource"
      description: |
        Get all events that occurred on the resource from device with given `deviceId` addressable at given `resourceHref`. Alternative is to call 'Get resource events' with `resourceIdFilter` query parameter.
      parameters:
        - $ref: "#/components/parameters/timestampFilter"
      security:
        - oauth2:
            - "plgd.devices"
      responses:
        200:
          $ref: "#/components/responses/events"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
  "/api/v1/ws/events":
    post:
      tags:
        - "Resource Events"
      summary: "Subscribe to events"
      description: |
        Open a websocket stream and receive events from devices. The contents of filters in the SubscribeToEvents message determine which events will be sent to the stream.
        Subscription doesn't guarantee that all events will be sent to the client. The client is responsible for synchronizing events.
      security:
        - oauth2:
            - "plgd.devices"
      requestBody:
        description: "SubscribeToEvents message that opens a websocket stream"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubscribeToEvents"
        required: true
      responses:
        200:
          description: "Stream of events"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Event"
        400:
          $ref: "#/components/responses/badRequest"
        401:
          $ref: "#/components/responses/unauthorized"
        403:
          $ref: "#/components/responses/forbidden"
        404:
          $ref: "#/components/responses/notFound"
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: The default OAuth API Resources.
      flows:
        implicit:
          authorizationUrl: https://auth.plgd.cloud/authorize?audience=https://try.plgd.cloud
          scopes:
            openid: to authorize access to a user's details
  requestBodies:
    authorizationContext:
      description: An access token must be send in the first message for backend mode via websocket.
      content:
        application/json:
          schema:
            type: object
            properties:
              token:
                type: string
                description: Access token
            example:
              Token: 53080a4f-5e3e-4291-802f-3436238232d1
  schemas:
    AuditContext:
      type: object
      properties:
        userId:
          type: string
        correlationId:
          type: string
    OAuthResponse:
      type: object
      properties:
        code:
          description: Device onboarding code
          type: string
    HubConfiguration:
      type: object
      properties:
        jwtOwnerClaim:
          description: JWT claim identifying device owner.
          type: string
          default: "sub"
        jwtDeviceIdClaim:
          description: JWT claim identifying device id. Empty means that JWT doesn't contain it.
          type: string
        id:
          description: Unique ID of the cloud, required for device registration at the plgd hub.
          type: string
          format: uuid
        coapGateway:
          description: URL of the device endpoint - plgd CoAP Gateway where the device connects.
          type: string
        certificateAuthorities:
          description: Public key of the certificate authority issuing the plgd identity certificates.
          type: string
        defaultCommandTimeToLive:
          description: Exposes default command time to live in nanoseconds for CreateResource, RetrieveResource, UpdateResource, DeleteResource, and UpdateDeviceMetadata commands when it is zero value in the request. 0 - means forever.
          type: integer
          format: int64
        currentTime:
          description: Current time of server in nanoseconds.
          type: integer
          format: int64
        authority:
          description: URL of the authorization server.
          type: string
        httpGatewayAddress:
          description: address where plgd HTTP Gateway handles API calls.
          type: string
        webOauthClient:
          $ref: '#/components/schemas/webOAuthClient'
        deviceOauthClient:
          $ref: '#/components/schemas/deviceOAuthClient'
        ui:
          $ref: '#/components/schemas/UIConfiguration'
        buildInfo:
          $ref: '#/components/schemas/buildInfo'
      example:
        jwtOwnerClaim: "sub"
        authority: "https://auth.plgd.cloud/realms/shared"
        id: "adebc667-1f2b-41e3-bf5c-6d6eabc68cc6"
        coapGateway: "coaps+tcp://try.plgd.cloud:5684"
        cloudAuthorizationProvider: "plgd"
        currentTime: 1629728394151716523
        defaultCommandTimeToLive: 0
        certificateAuthorities: |
          -----BEGIN CERTIFICATE-----
          MIIBRTCB66ADAgECAhAYrP/8939ZQulrospE3RuHMAoGCCqGSM49BAMCMBIxEDAO
          BgNVBAMTB1Jvb3QgQ0EwHhcNMjAwODE3MDcyMzM3WhcNMjEwODE3MDcyMzM3WjAS
          MRAwDgYDVQQDEwdSb290IENBMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEad6z
          XxjrEezHI8IvNH8RZkc10CM2CdaeU0S+azvpEqV+LMIh0CFLHw9WLEUaTV8JBmXU
          m2Ien4YsLfHbAC4Q/6MjMCEwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMB
          Af8wCgYIKoZIzj0EAwIDSQAwRgIhAIyyCjzD8YzCNSY6YbnLgJ7TaXz5HPE0Eyqm
          gfQCLUhwAiEAmfMN+GW05NyB3n5OxYHqVmHGDZJ8rHUUBCPJ3WbCweM=
          -----END CERTIFICATE-----
        deviceOauthClient:
          audience: "https://try.plgd.cloud"
          clientId: "cYN3p6lwNcNlOvvUhz55KvDZLQbJeDr5"
          providerName: "plgd.web"
          scopes: [ "offline_access" ]
        httpGatewayAddress: "https://api.try.plgd.cloud"
        webOauthClient: 
          audience: "https://try.plgd.cloud"
          clientId: "LXZ9OhKWWRYqf12W0B5OXduqt02q0zjS"
          scopes: [ "openid"]
        buildInfo:
          version: "2.7.19"
          commitHash: "abfe0011"
          commitDate: "2023-07-04T15:30:33Z"
          buildDate: "2023-07-04T15:31:17Z"
        ui:
          visibility:
            mainSidebar:
              certificates : true
              chatRoom : true
              configuration : true
              deviceProvisioning : true
              devices : true
              docs : true
              pendingCommands : true
              remoteClients : true
    webOAuthClient:
      type: object
      properties:
        clientId:
          description: Client ID of the web OAuth client.
          type: string
        audience:
          description: Audience of the web OAuth client.
          type: string
        scopes:
          description: Scopes of the web OAuth client.
          type: array
          items:
            type: string
    deviceOAuthClient:
      type: object
      properties:
        clientId:
          description: Client ID of the device OAuth client.
          type: string
        audience:
          description: Audience of the device OAuth client.
          type: string
        providerName:
          description: Provider name of the device OAuth client.
          type: string
        scopes:
          description: Scopes of the device OAuth client.
          type: array
          items:
            type: string
    buildInfo:
      type: object
      properties:
        version:
          type: string
          description: Version of the hub
        buildDate:
          type: string
          format: date-time
          description: build date of the hub
        commitHash:
          type: string
          description: commit hash of the hub
        commitDate:
          type: string
          format: date-time
          description: commit date of the hub
    CommandType:
      type: string
      enum:
        - "RESOURCE_CREATE"
        - "RESOURCE_RETRIEVE"
        - "RESOURCE_UPDATE"
        - "RESOURCE_DELETE"
        - "DEVICE_METADATA_UPDATE"
    resourceCommandType:
      type: string
      enum:
        - "RESOURCE_CREATE"
        - "RESOURCE_RETRIEVE"
        - "RESOURCE_UPDATE"
        - "RESOURCE_DELETE"
    ConnectionStatus:
      type: string
      enum:
        - "OFFLINE"
        - "ONLINE"
      default: "OFFLINE"
    Content:
      type: object
      properties:
        data:
          type: string
          format: byte
        contentType:
          type: string
        coapContentFormat:
          type: integer
          format: int32
    Device:
      type: object
      properties:
        id:
          type: string
        types:
          type: array
          items:
            type: string
        name:
          type: string
        metadata:
          $ref: "#/components/schemas/DeviceMetadata"
        manufacturerName:
          type: array
          items:
            type: object
            properties:
              language:
                type: string
              value:
                type: string
        modelNumber:
          type: string
        interfaces:
          type: array
          items:
            type: string
        protocolIndependentId:
          type: string
      example:
        id: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
        types:
          - "oic.d.cloudDevice"
          - "oic.wk.d"
        name: "CloudServer"
        metadata:
          connection:
            status: "ONLINE"
          twinEnabled: true
        manufacturerName:
          - language: "en-US"
            value: "plugged"
        modelNumber: "12-d21d4-23jzi2"
        interfaces:
          - "oic.if.r"
          - "oic.if.baseline"
        protocolIndependentId: "cd5f73ed-51e0-4ad7-59f9-bfb0f7b4b747"
    DeviceMetadata:
      type: object
      properties:
        status:
          type: object
          properties:
            value:
              $ref: "#/components/schemas/ConnectionStatus"
            validUntil:
              type: string
              format: int64
              description: "Unix timestamp in nanoseconds."
            connectedAt:
              type: string
              format: int64
              description: "Unix timestamp in nanoseconds."
            serviceId:
              type: string
              description: "The service.ID, which identify the device being served, must be set when the status is ONLINE. However, during an OFFLINE event, they will be sed to empty values."
            localEndpoints:
              type: array
              description: "The last local endpoints of the device, and it is set when the status is ONLINE."
              items:
                type: string
        twinSynchronization:
          $ref: "#/components/schemas/TwinSynchronization"
        twinEnabled:
          $ref: "#/components/schemas/TwinEnabled"
    DeviceMetadataSnapshotTaken:
      type: object
      properties:
        deviceId:
          type: string
        deviceMetadataUpdated:
          $ref: "#/components/schemas/DeviceMetadataUpdated"
        updatePendings:
          type: array
          items:
            $ref: "#/components/schemas/DeviceMetadataUpdatePending"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    DeviceMetadataUpdated:
      type: object
      properties:
        deviceId:
          type: string
        status:
          $ref: "#/components/schemas/ConnectionStatus"
        twinEnabled:
          $ref: "#/components/schemas/TwinEnabled"
        twinSynchronization:
          $ref: "#/components/schemas/TwinSynchronization"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    DeviceMetadataUpdatePending:
      type: object
      properties:
        deviceId:
          type: string
        twinEnabled:
          $ref: "#/components/schemas/TwinEnabled"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    Event:
      type: object
      properties:
        subscriptionId:
          type: string
        correlationId:
          type: string
        deviceRegistered:
          $ref: "#/components/schemas/EventDeviceRegistered"
        deviceUnregistered:
          $ref: "#/components/schemas/EventDeviceUnregistered"
        resourcePublished:
          $ref: "#/components/schemas/ResourceLinksPublished"
        resourceUnpublished:
          $ref: "#/components/schemas/ResourceLinksUnpublished"
        resourceChanged:
          $ref: "#/components/schemas/ResourceChanged"
        operationProcessed:
          $ref: "#/components/schemas/EventOperationProcessed"
        subscriptionCanceled:
          $ref: "#/components/schemas/EventSubscriptionCanceled"
        resourceUpdatePending:
          $ref: "#/components/schemas/ResourceUpdatePending"
        resourceUpdated:
          $ref: "#/components/schemas/ResourceUpdated"
        resourceRetrievePending:
          $ref: "#/components/schemas/ResourceRetrievePending"
        resourceRetrieved:
          $ref: "#/components/schemas/ResourceRetrieved"
        resourceDeletePending:
          $ref: "#/components/schemas/ResourceDeletePending"
        resourceDeleted:
          $ref: "#/components/schemas/ResourceDeleted"
        resourceCreatePending:
          $ref: "#/components/schemas/ResourceCreatePending"
        resourceCreated:
          $ref: "#/components/schemas/ResourceCreated"
        deviceMetadataUpdatePending:
          $ref: "#/components/schemas/DeviceMetadataUpdatePending"
        deviceMetadataUpdated:
          $ref: "#/components/schemas/DeviceMetadataUpdated"
    EventDeviceRegistered:
      type: object
      properties:
        deviceIds:
          type: array
          items:
            type: string
    EventDeviceUnregistered:
      type: object
      properties:
        deviceIds:
          type: array
          items:
            type: string
    EventMetadata:
      type: object
      properties:
        version:
          type: string
          format: uint64
        timestamp:
          type: string
          format: int64
        connectionId:
          type: string
        sequence:
          type: string
          format: uint64
    EventOperationProcessed:
      type: object
      properties:
        errorStatus:
          $ref: "#/components/schemas/OperationProcessedErrorStatus"
    EventSubscriptionCanceled:
      type: object
      properties:
        reason:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              typeUrl:
                type: string
              value:
                type: string
                format: byte
    ErrorStatusCode:
      type: string
      default: "OK"
      enum:
        - "OK"
        - "ERROR"
        - "NOT_FOUND"
    OperationProcessedErrorStatus:
      type: object
      properties:
        code:
          $ref: "#/components/schemas/ErrorStatusCode"
        message:
          type: string
    Resource:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        content:
          oneOf:
            - $ref: "#/components/schemas/ResourceContent"
            - $ref: "#/components/schemas/ResourceCreatedContent"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
        status:
          $ref: "#/components/schemas/Status"
      example:
        resourceId:
          href: "/switches/1"
          deviceId: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
        content:
          rt:
            - "oic.r.switch.binary"
          if:
            - "oic.if.a"
            - "oic.if.baseline"
          value: false
        auditContext:
          userId: "9772fcff-dcfb-4db8-a6c9-1b75f2165eb1"
          correlationId: "e20f1eef-2eeb-4755-b33e-139106d28e2c"
        eventMetadata:
          connectionId: "194.1.25.111:61692"
          sequence: "7"
          version: "0"
          timestamp: "1625427236429144178"
        status: "OK"
    ResourceChanged:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
        status:
          $ref: "#/components/schemas/Status"
    ResourceContent:
      type: object
      example:
        value: true
    ResourceCreateContent:
      type: object
      properties:
        rt:
          type: array
          items:
            type: string
        if:
          type: array
          items:
            type: string
        rep:
          description: "Resource content provided as JSON object or base64 encoded CBOR."
          type: object
        p:
          type: object
          properties:
            bm:
              type: integer
              default: 3
          required:
            - bm
      required:
        - rt
        - if
        - rep
        - p
      example:
        rt:
          - "oic.r.switch.binary"
        if:
          - "oic.if.a"
          - "oic.if.baseline"
        rep:
          value: false
        p:
          bm: 3
    ResourceCreated:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        status:
          $ref: "#/components/schemas/Status"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceCreatedContent:
      type: object
      properties:
        href:
          type: string
          format: uri
        rt:
          type: array
          items:
            type: string
        if:
          type: array
          items:
            type: string
        rep:
          description: "Resource content provided as JSON object or base64 encoded CBOR."
          type: object
      example:
        href: "/switches/1"
        rt:
          - "oic.r.switch.binary"
        if:
          - "oic.if.a"
          - "oic.if.baseline"
        rep:
          value: false
    ResourceCreatePending:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceDeleted:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        status:
          $ref: "#/components/schemas/Status"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceDeletePending:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceId:
      type: object
      properties:
        deviceId:
          type: string
          format: uuid
        href:
          type: string
          format: url
    ResourceLink:
      type: object
      properties:
        href:
          type: string
        deviceId:
          type: string
        resourceTypes:
          type: array
          items:
            type: string
        interfaces:
          type: array
          items:
            type: string
        anchor:
          type: string
        title:
          type: string
        supportedContentTypes:
          type: array
          items:
            type: string
        validUntil:
          type: string
          format: int64
        policy:
          type: object
          properties:
            bitFlags:
              type: integer
              format: int32
        endpointInformations:
          type: array
          items:
            type: object
            properties:
              endpoint:
                type: string
              priority:
                type: string
                format: int64
    ResourceLinks:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: "#/components/schemas/ResourceLink"
        deviceId:
          type: string
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
      example:
        resources:
          - href: "/switches/1"
            deviceId: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
            resourceTypes:
              - "oic.r.switch.binary"
            interfaces:
              - "oic.if.a"
              - "oic.if.baseline"
            anchor: ""
            title: ""
            supportedContentTypes: []
            validUntil: "0"
            policy:
              bitFlags: 3
            endpointInformations: []
        deviceId: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
        auditContext:
          userId: "9772fcff-dcfb-4db8-a6c9-1b75f2165eb1"
          correlationId: "ef007f88-6073-4af1-8951-971578bf6803"
        eventMetadata:
          connectionId: "194.1.25.111:61692"
          sequence: "4"
          version: "0"
          timestamp: "1625432924483895839"
    ResourceLinksPublished:
      $ref: "#/components/schemas/ResourceLinks"
    ResourceLinksSnapshotTaken:
      type: object
      properties:
        resources:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Resource"
        deviceId:
          type: string
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
    ResourceLinksUnpublished:
      type: object
      properties:
        hrefs:
          type: array
          items:
            type: string
        deviceId:
          type: string
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
      example:
        hrefs: ["/light/1", "/light/2"]
        deviceId: "4629b3cb-3a6e-477c-5d50-ccb28ad7c349"
        auditContext:
          userId: "9772fcff-dcfb-4db8-a6c9-1b75f2165eb1"
          correlationId: "ef007f88-6073-4af1-8951-971578bf6803"
        eventMetadata:
          connectionId: "194.1.25.111:61692"
          sequence: "4"
          version: "0"
          timestamp: "1625432924483895839"
    ResourceRetrieved:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        status:
          $ref: "#/components/schemas/Status"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceRetrievePending:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        resourceInterface:
          type: string
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceStateSnapshotTaken:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        latestResourceChange:
          $ref: "#/components/schemas/ResourceChanged"
        resourceCreatePendings:
          type: array
          items:
            $ref: "#/components/schemas/ResourceCreatePending"
        resourceRetrievePendings:
          type: array
          items:
            $ref: "#/components/schemas/ResourceRetrievePending"
        resourceUpdatePendings:
          type: array
          items:
            $ref: "#/components/schemas/ResourceUpdatePending"
        resourceDeletePendings:
          type: array
          items:
            $ref: "#/components/schemas/ResourceDeletePending"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceUpdated:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        status:
          $ref: "#/components/schemas/Status"
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    ResourceUpdatePending:
      type: object
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        resourceInterface:
          type: string
        content:
          $ref: "#/components/schemas/Content"
        auditContext:
          $ref: "#/components/schemas/AuditContext"
        eventMetadata:
          $ref: "#/components/schemas/EventMetadata"
    TwinEnabled:
      type: boolean
      default: true
    TwinSynchronization:
      type: object
      properties:
        state:
          $ref: "#/components/schemas/TwinSynchronizationState"
        syncingAt:
          type: string
          format: int64
        inSyncAt:
          type: string
          format: int64
        commandMetadata:
          $ref: "#/components/schemas/CommandMetadata"
    TwinSynchronizationState:
      type: string
      enum:
        - "OUT_OF_SYNC"
        - "DISABLED"
        - "SYNCING"
        - "IN_SYNC"
      default: "OUT_OF_SYNC"
      description: |
        OUT_OF_SYNC - As soon as it connects after it was offline or when it goes errorless offline or when twin enabled has been changed to true.
        DISABLED - As soon as twin enabled is set to false.
        SYNCING - As soon as device connects, successfully signs in and batch observe is called on device from the cloud.
        IN_SYNC - As soon as current device resources values are received and applied to twin database. Twin was successfully reconciled after device reconnect and is kept up to date using an active subscription to device resource changes.
    CommandMetadata:
      type: object
      properties:
        connectionId:
          type: string
        sequence:
          type: string
          format: uint64
    Status:
      type: string
      enum:
        - "UNKNOWN"
        - "OK"
        - "BAD_REQUEST"
        - "UNAUTHORIZED"
        - "FORBIDDEN"
        - "NOT_FOUND"
        - "UNAVAILABLE"
        - "NOT_IMPLEMENTED"
        - "ACCEPTED"
        - "ERROR"
        - "METHOD_NOT_ALLOWED"
        - "CREATED"
        - "NOT_MODIFIED"
    SubscribeToEvents:
      type: object
      properties:
        createSubscription:
          $ref: "#/components/schemas/SubscribeToEventsCreateSubscription"
        cancelSubscription:
          $ref: "#/components/schemas/SubscribeToEventsCancelSubscription"
        correlationId:
          type: string
    SubscribeToEventsCancelSubscription:
      type: object
      properties:
        subscriptionId:
          type: string
    SubscribeToEventsCreateSubscription:
      type: object
      description: |
        If you want to subscribe to all events, leave the filter unset.  
        Use the eventFilter in conjunction with other filters to filter events by type. If eventFilter is set, only events with the specified type will be received.  
        To filter devices, use the deviceIdFilter. It follows the format {deviceID[0]+\"/*\", deviceID[1]+\"/*\", ...}.  
        To filter resources, use the hrefFilter. It follows the format {\"*\"+href[0], \"*\"+href[1], ...}.  
        When both deviceIdFilter and hrefFilter are set, the hrefFilter is applied to each device. {deviceID[0]href[0], ..., deviceID[1]href[0], ...}.  
        To filter resources of specific devices, use the resourceIdFilter.  
        You can use either deviceIdFilter or resourceIdFilter or both. In this case, the result is the union of both filters.  
        Certain filters perform a logical \"or\" operation among the elements of the filter.  
      properties:
        eventFilter:
          type: array
          items:
            $ref: "#/components/schemas/SubscribeToEventsCreateSubscriptionEvent"       
        deviceIdFilter:
          type: array
          items:
            type: string
        hrefFilter:
          type: array
          items:
            type: string
        resourceIdFilter:
          type: array
          items:
            type: string
            format: "{deviceId}{href}"
    SubscribeToEventsCreateSubscriptionEvent:
      type: string
      default: "REGISTERED"
      enum:
        - "REGISTERED"
        - "UNREGISTERED"
        - "DEVICE_METADATA_UPDATED"
        - "DEVICE_METADATA_UPDATE_PENDING"
        - "RESOURCE_PUBLISHED"
        - "RESOURCE_UNPUBLISHED"
        - "RESOURCE_UPDATE_PENDING"
        - "RESOURCE_UPDATED"
        - "RESOURCE_RETRIEVE_PENDING"
        - "RESOURCE_RETRIEVED"
        - "RESOURCE_DELETE_PENDING"
        - "RESOURCE_DELETED"
        - "RESOURCE_CREATE_PENDING"
        - "RESOURCE_CREATED"
        - "RESOURCE_CHANGED"
    UIVisibilityMainSidebar:
      type: object
      properties:
        devices:
          type: boolean
        configuration:
          type: boolean
        remoteClients:
          type: boolean
        pendingCommands:
          type: boolean
        certificates:
          type: boolean
        deviceProvisioning:
          type: boolean
        docs:
          type: boolean
        chatRoom:
          type: boolean
        dashboard:
          type: boolean
        integrations:
          type: boolean
        deviceFirmwareUpdate:
          type: boolean
        deviceLogs:
          type: boolean
        apiTokens:
          type: boolean
        schemaHub:
          type: boolean
    UIConfiguration:
      title: UI configuration
      type: object
      properties:
        visibility:
          $ref: "#/components/schemas/UIVisibility"
          title: "Visibility"
        deviceProvisioningService:
          type: string
          title: "Address to device provisioning service HTTP API in format https://host:port"
    UIVisibility:
      type: object
      description: |
        true - show, false - hide
      properties:
        mainSidebar:
          $ref: "#/components/schemas/UIVisibilityMainSidebar"
          title: "Main sidebar visibility"
  parameters:
    deviceId:
      name: deviceId
      in: path
      description: "Id of the device."
      required: true
      schema:
        type: string
        format: uuid
    resourceHref:
      name: resourceHref
      in: path
      description: "Href of the resource."
      required: true
      schema:
        type: string
    shadow:
      name: shadow
      in: query
      description: "Bypass resource shadow and send the GET request directly to the device."
      schema:
        type: boolean
        default: true
    deviceIdFilter:
      name: deviceId
      in: query
      description: "Filter by the device id."
      schema:
        type: string
        format: uuid
    typeFilter:
      name: type
      in: query
      description: "Filter by the type."
      schema:
        type: array
        items:
          type: string
    statusFilter:
      name: status
      in: query
      description: "Filter by the device status."
      schema:
        type: array
        items:
          $ref: "#/components/schemas/ConnectionStatus"
    interface:
      name: interface
      in: query
      description: "Defines the view or a way how to interact with a resource."
      schema:
        type: string
    resourceIdFilter:
      name: resourceId
      in: query
      description: |
        Filter by resource id specified in format `{deviceId}{resourceHref}(?etag={etag})`.
        ETag is optional and it is supported only for GET resources.
      schema:
        type: array
        items:
          type: string
          format: urlEncoded
    commandFilter:
      name: command
      in: query
      description: "Filter by the command type."
      schema:
        type: array
        items:
          $ref: "#/components/schemas/CommandType"
    resourceCommandFilter:
      name: command
      in: query
      description: "Filter by the command type."
      schema:
        type: array
        items:
          $ref: "#/components/schemas/resourceCommandType"
    timestampFilter:
      name: timestamp
      in: query
      description: "Filter by Unix nanoseconds timestamp"
      schema:
        type: integer
        format: int64
    timeToLive:
      name: timeToLive
      in: query
      description: "Command expiration in nanoseconds. 0 means forever and 100ms is minimal value."
      schema:
        type: integer
        format: int64
        default: 0
        minimum: 100000000
    correlationIdFilter:
      name: correlationIdFilter
      in: query
      description: "Filter by the correlationId."
      schema:
        type: string
        format: uuid
    etag:
      name: ETag
      in: header
      description: "ETag of the resource."
      schema:
        type: string
        format: base64
    onlyContent:
      name: onlyContent
      in: query
      description: "Return only content of the resource in the response."
      schema:
        type: boolean
        default: false
  responses:
    ok:
      description: Content is stored in body.
    nocontent:
      description: No content in body.
    accepted:
      description: Action will asynchronously processed.
    unauthorized:
      description: Not authorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                $ref: "#/components/schemas/Error"
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                $ref: "#/components/schemas/Error"
    badRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                $ref: "#/components/schemas/Error"
    notFound:
      description: "Entity was not found."
    pendingCommands:
      description: "Stream of resource links or errors."
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                $ref: "#/components/schemas/ResourceLinks"
              error:
                $ref: "#/components/schemas/Error"
    canceledCommands:
      description: "Correlation ids of all successfully canceled commands."
      content:
        application/json:
          schema:
            type: object
            properties:
              correlationIds:
                type: array
                items:
                  type: string
                  format: uuid
    events:
      description: "Stream of events or error"
      content:
        application/json:
          schema:
            type: array
            items:
              properties:
                result:
                  properties:
                    resourceLinksPublished:
                      $ref: "#/components/schemas/ResourceLinksPublished"
                    resourceLinksUnpublished:
                      $ref: "#/components/schemas/ResourceLinksUnpublished"
                    resourceLinksSnapshotTaken:
                      $ref: "#/components/schemas/ResourceLinksSnapshotTaken"
                    resourceChanged:
                      $ref: "#/components/schemas/ResourceChanged"
                    resourceUpdatePending:
                      $ref: "#/components/schemas/ResourceUpdatePending"
                    resourceUpdated:
                      $ref: "#/components/schemas/ResourceUpdated"
                    resourceRetrievePending:
                      $ref: "#/components/schemas/ResourceRetrievePending"
                    resourceRetrieved:
                      $ref: "#/components/schemas/ResourceRetrieved"
                    resourceDeletePending:
                      $ref: "#/components/schemas/ResourceDeletePending"
                    resourceDeleted:
                      $ref: "#/components/schemas/ResourceDeleted"
                    resourceCreatePending:
                      $ref: "#/components/schemas/ResourceCreatePending"
                    resourceCreated:
                      $ref: "#/components/schemas/ResourceCreated"
                    resourceStateSnapshotTaken:
                      $ref: "#/components/schemas/ResourceStateSnapshotTaken"
                    deviceMetadataUpdatePending:
                      $ref: "#/components/schemas/DeviceMetadataUpdatePending"
                    deviceMetadataUpdated:
                      $ref: "#/components/schemas/DeviceMetadataUpdated"
                    deviceMetadataSnapshotTaken:
                      $ref: "#/components/schemas/DeviceMetadataSnapshotTaken"
                error:
                  $ref: "#/components/schemas/Error"