REST API documentation version v1

Base URL: https://cloud.kaaiot.com/api/v1/am

Asset types

Operations on asset types.

post get
post

Creates a new item.

get

Retrieves list.

Creates a new item.

Secured by oauth_2_0 with scopes:
  • tenant:asset-type:create

AM supports OAuth 2.0 for authenticating all API requests.

Body

Media type: application/json

Type: object

Properties
  • type: required(string - pattern: ^[A-Z0-9_]{2,50}+$)

    Type.

  • displayName: required(string)

    Display name.

  • description: (string)

    Description.

  • definitionJsonSchema: required(string)

    Asset validation JSON schema.

  • uiJsonSchema: (string)

    UI JSON schema.

Example:

{
  "type": "BUILDING",
  "displayName": "building",
  "description": "Asset type that represents building",
  "definitionJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}"
}

HTTP status code 201

Item is successfully created.

Headers

  • Location: required(string)

    URI in format {schema}://{host}/am/api/v1/asset-types/{assetTypeId}

    Example:

    https://cloud.kaaiot.com/am/api/v1/asset-types/47e17fc5-060c-4923-b315-d17f6a1bf8d6

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties
  • message: required(string)

    Detailed error description.

HTTP status code 401

Request is not authenticated.

HTTP status code 403

Principal does not have sufficient permissions to perform this operation.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

get put delete
get

Retrieves item.

put

Updates item.

delete

Deletes.

Retrieves item.

Secured by oauth_2_0 with scopes:
  • asset-type:read

AM supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • assetTypeId: required(string)

    ID

HTTP status code 200

Item is successfully retrieved.

Body

Media type: application/json

Type: object

Properties
  • id: required(string)

    ID.

  • type: required(string - pattern: ^[A-Z0-9_]{2,50}+$)

    Type.

  • displayName: required(string)

    Display name.

  • description: (string)

    Description.

  • definitionJsonSchema: (string)

    Asset validation JSON schema.

  • uiJsonSchema: (string)

    UI JSON schema.

  • tenantId: required(object)

    Tenant ID.

    • createdAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the record was created.

      Example:

      2023-06-30T12:30:54.540Z
    • updatedAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the record was last updated.

      Example:

      2023-06-30T12:30:54.540Z

    Example:

    {
  "id": "47e17fc5-060c-4923-b315-d17f6a1bf8d6",
  "type": "BUILDING",
  "displayName": "building",
  "description": "Asset type that represents building",
  "tenantId": "f59a5f45-875d-4dcb-95eb-b017ef9a0638",
  "definitionJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
  "createdAt": "2023-06-30T12:30:54.540Z",
  "updatedAt": "2023-06-30T12:30:54.541Z"
}

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Updates item.

    Secured by oauth_2_0 with scopes:
    • asset-type:update

    AM supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • assetTypeId: required(string)

      ID

    Body

    Media type: application/json

    Type: object

    Properties
    • type: required(string - pattern: ^[A-Z0-9_]{2,50}+$)

      Type.

    • displayName: required(string)

      Display name.

    • description: (string)

      Description.

    • definitionJsonSchema: required(string)

      Asset validation JSON schema.

    • uiJsonSchema: (string)

      UI JSON schema.

    Example:

    {
  "type": "BUILDING",
  "displayName": "building",
  "description": "Asset type that represents building",
  "definitionJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}"
}

    HTTP status code 204

    Item is successfully updated.

    HTTP status code 400

    Invalid request.

    Body

    Media type: application/json

    Type: object

    Properties
    • message: required(string)

      Detailed error description.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Deletes.

    Secured by oauth_2_0 with scopes:
    • asset-type:delete

    AM supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • assetTypeId: required(string)

      ID

    HTTP status code 204

    Item is successfully deleted.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Assets

    Operations on assets.

    post
    post

    Creates a new item.

    Creates a new item.

    Secured by oauth_2_0 with scopes:
    • asset-type:asset:create

    AM supports OAuth 2.0 for authenticating all API requests.

    Body

    Media type: application/json

    Type: object

    Properties
    • assetTypeId: required(string)

      Asset type ID.

    • definition: required(string)

      Definition according to the asset type's JSON schema.

    • uiJsonSchema: (string)

      UI JSON schema.

    Example:

    {
  "assetTypeId": "d42e0139-b065-4965-8768-04da733f132c",
  "definition": "{\"city\":\"Kyiv\",\"street\":\"Khreshchatyk St\"}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}"
}

    HTTP status code 201

    Item is successfully created.

    Headers

    • Location: required(string)

      URI in format {schema}://{host}/am/api/v1/assets/{assetId}

      Example:

      https://cloud.kaaiot.com/am/api/v1/assets/47e17fc5-060c-4923-b315-d17f6a1bf8d6

    HTTP status code 400

    Invalid request.

    Body

    Media type: application/json

    Type: object

    Properties
    • message: required(string)

      Detailed error description.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 403

    Principal does not have sufficient permissions to perform this operation.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    post
    post

    Retrieves list with optional filtering by asset definition.

    Retrieves list with optional filtering by asset definition.

    Secured by oauth_2_0 with scopes:
    • asset:read

    AM supports OAuth 2.0 for authenticating all API requests.

    Query Parameters

    • assetTypeIds: (string)

      Asset type IDs.

    • assetIds: (string)

      Asset IDs.

    • page: (number - default: 0)

      Page number.

      Example:

      0
    • size: (number - default: 100)

      Page size.

      Example:

      10
    • sort: (one of createdAt, updatedAt - default: createdAt)

      Field to sort by.

      Example:

      updatedAt
    • sortOrder: (one of asc, desc - default: desc)

      Sort direction.

      Example:

      asc

    Body

    Media type: application/json

    Type: object

    Properties
    • and: required(array of asset.KeyValueFilter)

      And.

      Items: KeyValueFilter

      • key: required(string)

        Key.

      • in: required(array of string)

        Values that the key must be in.

      • matchMode: (one of EQUAL, LIKE - default: EQUAL)

        EQUAL - matches asset only if its key equal to one of the value in the in.
        LIKE - matches asset if its key is like one of the value in the in.

      • and: required(array of $recur)

        And.

      • or: required(array of $recur)

        Or.

    • or: required(array of asset.KeyValueFilter)

      Or.

      Items: KeyValueFilter

      • key: required(string)

        Key.

      • in: required(array of string)

        Values that the key must be in.

      • matchMode: (one of EQUAL, LIKE - default: EQUAL)

        EQUAL - matches asset only if its key equal to one of the value in the in.
        LIKE - matches asset if its key is like one of the value in the in.

      • and: required(array of $recur)

        And.

      • or: required(array of $recur)

        Or.

    Example:

    {
  "and": [
    {
      "key": "location.city",
      "in": [
        "Kyiv"
      ],
      "matchMode": "EQUAL"
    },
    {
      "or": [
        {
          "key": "location.street",
          "in": [
            "Khresh",
            "Shev"
          ],
          "matchMode": "LIKE"
        }
      ]
    }
  ]
}

    HTTP status code 200

    List is successfully retrieved.

    Body

    Media type: application/json

    Type: object

    Properties
    • totalElements: required(integer)

      Total number of elements available for retrieval.

    • content: required(array of asset.ItemResponse)

      Items: ItemResponse

      • id: required(string)

        ID.

      • assetTypeId: required(string)

        Asset type ID.

      • definition: required(string)

        Definition according to the asset type's JSON schema.

      • uiJsonSchema: (string)

        UI JSON schema.

      • tenantId: required(string)

        Tenant ID.

      • createdAt: required(datetime)

        Timestamp in ISO 8601 format (UTC timezone) showing when the record was created.

        Example:

        2023-06-30T12:30:54.540Z
      • updatedAt: required(datetime)

        Timestamp in ISO 8601 format (UTC timezone) showing when the record was last updated.

        Example:

        2023-06-30T12:30:54.540Z

    Example:

    {
  "content": [
    {
      "id": "47e17fc5-060c-4923-b315-d17f6a1bf8d6",
      "assetTypeId": "d42e0139-b065-4965-8768-04da733f132c",
      "definition": "{\"city\":\"Kyiv\",\"street\":\"Khreshchatyk St\"}",
      "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
      "tenantId": "f59a5f45-875d-4dcb-95eb-b017ef9a0638",
      "createdAt": "2023-06-30T12:30:54.540Z",
      "updatedAt": "2023-06-30T12:30:54.541Z"
    }
  ],
  "totalElements": 1
}

    HTTP status code 401

    Request is not authenticated.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    get put delete
    get

    Retrieves item.

    put

    Updates item.

    delete

    Deletes.

    Retrieves item.

    Secured by oauth_2_0 with scopes:
    • asset:read

    AM supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • assetId: required(string)

      ID

    HTTP status code 200

    Item is successfully retrieved.

    Body

    Media type: application/json

    Type: object

    Properties
    • id: required(string)

      ID.

    • assetTypeId: required(string)

      Asset type ID.

    • definition: required(string)

      Definition according to the asset type's JSON schema.

    • uiJsonSchema: (string)

      UI JSON schema.

    • tenantId: required(string)

      Tenant ID.

    • createdAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the record was created.

      Example:

      2023-06-30T12:30:54.540Z
    • updatedAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the record was last updated.

      Example:

      2023-06-30T12:30:54.540Z

    Example:

    {
  "id": "47e17fc5-060c-4923-b315-d17f6a1bf8d6",
  "assetTypeId": "d42e0139-b065-4965-8768-04da733f132c",
  "definition": "{\"city\":\"Kyiv\",\"street\":\"Khreshchatyk St\"}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}",
  "tenantId": "f59a5f45-875d-4dcb-95eb-b017ef9a0638",
  "createdAt": "2023-06-30T12:30:54.540Z",
  "updatedAt": "2023-06-30T12:30:54.541Z"
}

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Updates item.

    Secured by oauth_2_0 with scopes:
    • asset:update

    AM supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • assetId: required(string)

      ID

    Body

    Media type: application/json

    Type: object

    Properties
    • assetTypeId: required(string)

      Asset type ID.

    • definition: required(string)

      Definition according to the asset type's JSON schema.

    • uiJsonSchema: (string)

      UI JSON schema.

    Example:

    {
  "assetTypeId": "d42e0139-b065-4965-8768-04da733f132c",
  "definition": "{\"city\":\"Kyiv\",\"street\":\"Khreshchatyk St\"}",
  "uiJsonSchema": "{\"$id\":\"https://example.com/employee.schema.json\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"title\":\"Vehicleassettype\",\"description\":\"Vehicleassettype\",\"type\":\"object\",\"properties\":{\"make\":{\"description\":\"Make\",\"type\":\"string\"},\"model\":{\"description\":\"Model\",\"type\":\"string\"},\"license_plate_number\":{\"description\":\"Licenseplatenumber\",\"type\":\"string\"}}}"
}

    HTTP status code 204

    Item is successfully updated.

    HTTP status code 400

    Invalid request.

    Body

    Media type: application/json

    Type: object

    Properties
    • message: required(string)

      Detailed error description.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Deletes.

    Secured by oauth_2_0 with scopes:
    • asset:delete

    AM supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • assetId: required(string)

      ID

    HTTP status code 204

    Item is successfully deleted.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 404

    Resource not found or querying user is not authorized for it.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Relations

    Operations on relations.

    get
    get

    Retrieves relations.

    post

    Creates relation

    Secured by oauth_2_0 with scopes:
    • endpoint:update
    • asset:update

    AM supports OAuth 2.0 for authenticating all API requests.

    Body

    Media type: application/json

    Type: object

    Properties
    • fromEntityId: required(string)

      From entity ID.

    • fromEntityType: required(one of ENDPOINT, ASSET, ASSET_TYPE, APPLICATION)

      From entity type.

    • toEntityId: required(string)

      To entity ID.

    • toEntityType: required(one of ENDPOINT, ASSET, ASSET_TYPE, APPLICATION)

      To entity type.

    • relationType: required(one of CONTAINS, SUPPORTS, MANAGES, CONTROLS)

      Relation type.

    Example:

    {
  "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f",
  "fromEntityType": "ASSET",
  "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c",
  "toEntityType": "ENDPOINT",
  "relationType": "CONTAINS"
}

    HTTP status code 200

    Relation is successfully created.

    HTTP status code 400

    Invalid request.

    Body

    Media type: application/json

    Type: object

    Properties
    • message: required(string)

      Detailed error description.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 403

    Principal does not have sufficient permissions to perform this operation.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    post

    Deletes relation

    Secured by oauth_2_0 with scopes:
    • endpoint:update
    • asset:update

    AM supports OAuth 2.0 for authenticating all API requests.

    Body

    Media type: application/json

    Type: object

    Properties
    • fromEntityId: required(string)

      From entity ID.

    • fromEntityType: required(one of ENDPOINT, ASSET, ASSET_TYPE, APPLICATION)

      From entity type.

    • toEntityId: required(string)

      To entity ID.

    • toEntityType: required(one of ENDPOINT, ASSET, ASSET_TYPE, APPLICATION)

      To entity type.

    • relationType: required(one of CONTAINS, SUPPORTS, MANAGES, CONTROLS)

      Relation type.

    Example:

    {
  "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f",
  "fromEntityType": "ASSET",
  "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c",
  "toEntityType": "ENDPOINT",
  "relationType": "CONTAINS"
}

    HTTP status code 200

    Relation is successfully deleted.

    HTTP status code 400

    Invalid request.

    Body

    Media type: application/json

    Type: object

    Properties
    • message: required(string)

      Detailed error description.

    HTTP status code 401

    Request is not authenticated.

    HTTP status code 403

    Principal does not have sufficient permissions to perform this operation.

    Secured by oauth_2_0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Relation sessions

    Operations on relation sessions.

    get
    get

    Retrieves relation sessions.

    Relation trees

    Operations on relation trees.

    get
    get

    Retrieves relation tree.