{ "openapi": "3.0.3", "info": { "title": "REST API documentation", "version": "v1", "description": "" }, "servers": [ { "url": "https://cloud.kaaiot.com/am", "description": "API Server" } ], "paths": { "/api/v1/asset-types": { "post": { "description": "Creates a new item.", "responses": { "201": { "description": "Item is successfully created.", "headers": { "Location": { "description": "URI in format `{schema}://{host}/am/api/v1/asset-types/{assetTypeId}`", "schema": { "type": "string" } } } } }, "security": [ { "oauth_2_0": [ "tenant:asset-type:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" }, "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\"}}}", "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } }, "get": { "description": "Retrieves list.", "responses": { "200": { "description": "List is successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" }, "example": { "content": [ { "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" } ], "totalElements": 1 } } } } }, "security": [ { "oauth_2_0": [ "asset-type:read" ] } ], "parameters": [ { "name": "type", "in": "query", "description": "Type. Supports partial match.", "required": false, "schema": { "type": "string" }, "example": "BUILDING" }, { "name": "description", "in": "query", "description": "Description. Supports partial match.", "required": false, "schema": { "type": "string" }, "example": "myDescription" } ] } }, "/api/v1/asset-types/{assetTypeId}": { "parameters": [ { "name": "assetTypeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID" } ], "get": { "description": "Retrieves item.", "responses": { "200": { "description": "Item is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "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" } } } } }, "security": [ { "oauth_2_0": [ "asset-type:read" ] } ] }, "put": { "description": "Updates item.", "responses": { "204": { "description": "Item is successfully updated." } }, "security": [ { "oauth_2_0": [ "asset-type:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRequest" }, "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\"}}}" } } } } }, "delete": { "description": "Deletes.", "responses": { "204": { "description": "Item is successfully deleted." } }, "security": [ { "oauth_2_0": [ "asset-type:delete" ] } ] } }, "/api/v1/assets": { "post": { "description": "Creates a new item.", "responses": { "201": { "description": "Item is successfully created.", "headers": { "Location": { "description": "URI in format `{schema}://{host}/am/api/v1/assets/{assetId}`", "schema": { "type": "string" } } } } }, "security": [ { "oauth_2_0": [ "asset-type:asset:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "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\"}}}", "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ] } } } } } }, "/api/v1/assets/list": { "post": { "description": "Retrieves list with optional filtering by asset definition.", "responses": { "200": { "description": "List is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "content": [ { "id": "47e17fc5-060c-4923-b315-d17f6a1bf8d6", "assetTypeId": "d42e0139-b065-4965-8768-04da733f132c", "definition": "{\"city\":\"Kyiv\",\"street\":\"Khreshchatyk St\"}", "uiJsonSchema": "{\"$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 } } } } }, "security": [ { "oauth_2_0": [ "asset:read" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetFilter" }, "example": { "assetIds": [ "asset_39379d45-661c-4b66-98aa-5cc97303c177", "asset_39379d45-661c-4b66-98aa-5cc97303c178" ], "assetTypeIds": [ "asset_tp_d626bba5-d316-41eb-afcc-76f2980233c2", "asset_tp_d626bba5-d316-41eb-afcc-76f2980233c3" ], "and": [ { "key": "location.city", "in": [ "Kyiv" ], "matchMode": "EQUAL" }, { "or": [ { "key": "location.street", "in": [ "Khresh", "Shev" ], "matchMode": "LIKE" } ] } ], "sort": { "key": "location.city", "direction": "DESC" } } } } } } }, "/api/v1/assets/{assetId}": { "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID" } ], "get": { "description": "Retrieves item.", "responses": { "200": { "description": "Item is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "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", "poolIds": [ "aXJuOnJjNzNkYmg3cTA6aWFtY29yZTo0YXRjaWNuaXNnOjpwb29sL2Rldg==" ], "createdAt": "2023-06-30T12:30:54.540Z", "updatedAt": "2023-06-30T12:30:54.541Z" } } } } }, "security": [ { "oauth_2_0": [ "asset:read" ] } ] }, "put": { "description": "Updates item.", "responses": { "204": { "description": "Item is successfully updated." } }, "security": [ { "oauth_2_0": [ "asset:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "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\"}}}" } } } } }, "patch": { "description": "Patches item.", "responses": { "204": { "description": "Item is successfully patched." } }, "security": [ { "oauth_2_0": [ "asset:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRequest" }, "example": { "operations": [ { "op": "add", "path": "/address", "value": { "street": "Shevchenka", "apt": 43 } }, { "op": "copy", "from": "/city", "path": "/town" } ] } } } } }, "delete": { "description": "Deletes.", "responses": { "204": { "description": "Item is successfully deleted." } }, "security": [ { "oauth_2_0": [ "asset:delete" ] } ] } }, "/api/v2/relations": { "get": { "description": "Retrieves relations.", "responses": { "200": { "description": "Relations are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "content": [ { "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f", "fromEntityType": "ASSET", "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c", "toEntityType": "ENDPOINT", "relationType": "CONTAINS", "createdAt": "2024-02-02T01:23:29.841Z", "updatedAt": "2024-02-02T01:23:29.841Z" } ], "totalElements": 1 } } } } }, "security": [ { "oauth_2_0": [ "asset:read", "endpoint:read", "asset-type:read", "application:read" ] } ], "parameters": [ { "name": "entityIds", "in": "query", "description": "Entity IDs.", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/relations/link": { "post": { "description": "Creates relation", "responses": { "200": { "description": "Relation is successfully created." } }, "security": [ { "oauth_2_0": [ "endpoint:update", "asset:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAndUnlinkRequest" }, "example": { "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f", "fromEntityType": "ASSET", "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c", "toEntityType": "ENDPOINT", "relationType": "CONTAINS" } } } } } }, "/api/v1/relations/unlink": { "post": { "description": "Deletes relation", "responses": { "200": { "description": "Relation is successfully deleted." } }, "security": [ { "oauth_2_0": [ "endpoint:update", "asset:update" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": { "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f", "fromEntityType": "ASSET", "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c", "toEntityType": "ENDPOINT", "relationType": "CONTAINS" } } } } } }, "/api/v1/relation-sessions": { "get": { "description": "Retrieves relation sessions.", "responses": { "200": { "description": "Relation sessions are successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": [ { "fromEntityId": "68f3c94d-c713-471a-ba71-51cc2d0f285f", "fromEntityType": "ASSET", "toEntityId": "716036b6-090f-4155-8ee9-6063b4a98a9c", "toEntityType": "ENDPOINT", "relationType": "CONTAINS", "linkedAt": "2024-02-01T01:23:29.841Z", "unlinkedAt": "2024-02-02T01:23:29.903Z", "createdAt": "2024-02-02T01:23:29.841Z", "updatedAt": "2024-02-02T01:23:29.903Z" } ] } } } }, "security": [ { "oauth_2_0": [ "asset:read", "endpoint:read", "asset-type:read", "application:read" ] } ], "parameters": [ { "name": "entityId", "in": "query", "description": "Entity ID.", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/relation-trees": { "get": { "description": "Retrieves relation tree.", "responses": { "200": { "description": "Relation tree is successfully retrieved.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "IS_CONTAINED_BY": [ { "entityType": "ASSET", "entityId": "asset_3532943a-0a47-412c-a0c3-0b15da17e16b" } ], "CONTAINS": [ { "entityType": "ENDPOINT", "entityId": "43e15dfb-9307-4399-b0b0-538d4e6be419" }, { "entityType": "ENDPOINT", "entityId": "30f3a9f7-a7b4-4a95-887c-0d83f3c21055" } ] } } } } }, "security": [ { "oauth_2_0": [ "asset:read", "endpoint:read", "asset-type:read", "application:read" ] } ], "parameters": [ { "name": "entityType", "in": "query", "description": "Entity type.", "required": true, "schema": { "type": "string", "enum": [ "ENDPOINT", "ASSET", "ASSET_TYPE", "APPLICATION" ] } }, { "name": "entityId", "in": "query", "description": "Entity ID.", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "oauth_2_0": { "type": "oauth2", "description": "AM supports OAuth 2.0 for authenticating all API requests.\n", "flows": { "implicit": { "authorizationUrl": "https://auth.example.com/oauth/authorize", "scopes": {} } } } }, "schemas": { "CreateRequest": { "type": "object", "properties": { "assetTypeId": { "type": "string", "description": "Asset type ID." }, "definition": { "type": "string", "description": "Definition according to the asset type's JSON schema." }, "uiJsonSchema": { "type": "string", "description": "UI JSON schema." }, "poolIds": { "type": "array", "items": { "type": "string" }, "description": "An array of the unique identifiers of the pools to which the asset is attached." } }, "required": [ "assetTypeId", "definition" ] }, "ItemResponse": { "type": "object", "properties": { "fromEntityId": { "type": "string", "description": "From entity ID." }, "fromEntityType": { "type": "string", "description": "From entity type.", "enum": [ "ENDPOINT", "ASSET", "ASSET_TYPE", "APPLICATION" ] }, "toEntityId": { "type": "string", "description": "To entity ID." }, "toEntityType": { "type": "string", "description": "To entity type.", "enum": [ "ENDPOINT", "ASSET", "ASSET_TYPE", "APPLICATION" ] }, "relationType": { "type": "string", "description": "Relation type.", "enum": [ "CONTAINS", "SUPPORTS", "MANAGES", "CONTROLS" ] }, "linkedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the relation was linked at." }, "unlinkedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the relation was unlinked at." }, "createdAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the record was created." }, "updatedAt": { "type": "string", "format": "rfc3339", "description": "Timestamp in ISO 8601 format (UTC timezone) showing when the record was last updated." } }, "required": [ "fromEntityId", "fromEntityType", "toEntityId", "toEntityType", "relationType", "linkedAt", "createdAt", "updatedAt" ] }, "ListResponse": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of elements available for retrieval." }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/ItemResponse" } } }, "required": [ "totalElements" ] }, "UpdateRequest": { "type": "object", "properties": { "assetTypeId": { "type": "string", "description": "Asset type ID." }, "definition": { "type": "string", "description": "Definition according to the asset type's JSON schema." }, "uiJsonSchema": { "type": "string", "description": "UI JSON schema." } }, "required": [ "assetTypeId", "definition" ] }, "KeyValueFilter": { "type": "object", "properties": { "key": { "type": "string", "description": "Key." }, "in": { "type": "array", "items": { "type": "string" }, "description": "Values that the key must be in." }, "matchMode": { "type": "string", "description": "- EQUAL - matches asset only if its key equal to one of the value in the `in`.
\n- NOT_EQUAL - matches asset only if its key is not equal to any of the values in the `in`.\n- LIKE - matches asset if its key like one of the value in the `in`.\n- GT_EQ - matches asset if its key is greater than or equal to one of the value in the `in`.\n- LT_EQ - matches asset if its key is less than or equal to one of the value in the `in`.\n", "enum": [ "EQUAL", "NOT_EQUAL", "LIKE", "GT_EQ", "LT_EQ" ] }, "and": { "type": "array", "items": { "type": "object" }, "description": "And." }, "or": { "type": "array", "items": { "type": "object" }, "description": "Or." } }, "required": [ "key", "in", "and", "or" ] }, "Sort": { "type": "object", "properties": { "key": { "type": "string", "description": "Sorting key inside asset definition." }, "direction": { "type": "object", "description": "Sort direction.", "enum": [ "ASC", "DESC" ] } } }, "AssetFilter": { "type": "object", "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "Asset IDs." }, "assetTypeIds": { "type": "array", "items": { "type": "string" }, "description": "Asset type IDs" }, "and": { "type": "array", "items": { "$ref": "#/components/schemas/KeyValueFilter" }, "description": "And." }, "or": { "type": "array", "items": { "type": "object" }, "description": "Or." }, "sort": { "$ref": "#/components/schemas/Sort" }, "relationType": { "type": "string", "description": "Directed relation type. When specified, each asset in the response will include a `relations` field\ncontaining related assets grouped by relation type. Uses directed types to indicate the direction\nof the relation (e.g., CONTAINS returns assets that this asset contains, IS_CONTAINED_BY returns\nassets that contain this asset).\n", "enum": [ "CONTAINS", "IS_CONTAINED_BY", "SUPPORTS", "IS_SUPPORTED_BY", "MANAGES", "IS_MANAGED_BY", "CONTROLS", "IS_CONTROLLED_BY" ] } } }, "PatchRequest": { "type": "object", "properties": { "operations": { "type": "array", "items": {}, "description": "Array of HTTP patches according to RFC 6902." } }, "required": [ "operations" ] }, "LinkAndUnlinkRequest": { "type": "object", "properties": { "fromEntityId": { "type": "string", "description": "From entity ID." }, "fromEntityType": { "type": "string", "description": "From entity type.", "enum": [ "ENDPOINT", "ASSET", "ASSET_TYPE", "APPLICATION" ] }, "toEntityId": { "type": "string", "description": "To entity ID." }, "toEntityType": { "type": "string", "description": "To entity type.", "enum": [ "ENDPOINT", "ASSET", "ASSET_TYPE", "APPLICATION" ] }, "relationType": { "type": "string", "description": "Relation type.", "enum": [ "CONTAINS", "SUPPORTS", "MANAGES", "CONTROLS" ] } }, "required": [ "fromEntityId", "fromEntityType", "toEntityId", "toEntityType", "relationType" ] }, "RelatedEntity": { "type": "object", "properties": { "entityId": { "type": "string", "description": "ID of the related entity." }, "entityType": { "type": "string", "description": "Type of the related entity.", "enum": [ "ENDPOINT", "ASSET" ] } }, "required": [ "entityId", "entityType" ] }, "ClientErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Detailed error description." } }, "required": [ "message" ] } } } }