@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Hardware Sentry TrueSight Presentation Server REST API
@community true
@base /tsws/10.0/api/
@version 11.1.00
@auth ApiKey Cookie in header
@endpoints 23
@hint download_for_search
@toc hardware(23)

@endpoint POST /hardware/actions/{deviceId}/collect-now
@desc Triggers a new collect on a specific device.
@required {deviceId: int(int32) # The ID of the device., monitorClass: str # The Monitor Class of the device.}
@returns(200) Successful operation
@errors {403: Forbidden operation, 500: Unexpected error}

@endpoint POST /hardware/actions/{deviceId}/rediscover
@desc Triggers a new discovery on a specific device.
@required {deviceId: int(int32) # The ID of the device.}
@returns(200) Successful operation
@errors {403: Forbidden operation, 500: Unexpected error}

@endpoint POST /hardware/actions/{deviceId}/reinitialize
@desc Sends a 'Reinitialize KM' command.
@required {deviceId: int(int32) # The ID of the device.}
@optional {resetDiscoveryAndPollingIntervals: int(int32)(0/1) # When set to <em>1</em>, removes all user-defined frequencies for discovery and polling processes to their default values (respectively 1 hour and 2 minutes)., resetAlertAfterNTimes: int(int32)(0/1) # When set to <em>1</em>, resets the number of times thresholds can be breached before triggering an alert to their default values (1 time) for numeric, discrete, connector status and present parameters., resetAlertActions: int(int32)(0/1) # When set to <em>1</em>, removes all manually set Alert Actions and reverts to basic default actions i.e. trigger a PATROL event and annotate a parameter graph., resetOtherAlertSettings: int(int32)(0/1) # When set to <em>1</em>, reverts any manually performed configuration changes to the default Hardware Sentry values., resetDebugMode: int(int32)(0/1) # When set to <em>1</em>, deactivates the debug mode when it was manually enabled., resetRemovedPausedObjectList: int(int32)(0/1) # When set to <em>1</em>, reactivates the monitoring of all paused or removed objects., resetReportSettings: int(int32)(0/1) # When set to <em>1</em>, clears the report schedule., resetJavaSettings: int(int32)(0/1) # When set to <em>1</em>, removes the custom Java settings (path and credentials). The KM will try to automatically find a suitable JRE., resetThresholds: int(int32)(0/1) # When set to <em>1</em>, resets all thresholds.}
@returns(200) Successful operation
@errors {403: Forbidden operation, 500: Unexpected error}

@endpoint POST /hardware/actions/{deviceId}/remove
@desc Removes a specific instance from the monitoring environment.
@required {deviceId: int(int32) # The ID of the device., monitorClass: str # The Monitor Class of the device., monitorSid: str # The Monitor SID of the device.}
@returns(200) Successful operation
@errors {403: Forbidden operation, 500: Unexpected error}

@endpoint POST /hardware/actions/{deviceId}/reset-error-count
@desc Resets the Error Count parameter.
@required {deviceId: int(int32) # The ID of the device., monitorClass: str # The Monitor Class of the device., monitorSid: str # The Monitor SID of the device.}
@returns(200) Successful operation
@errors {403: Forbidden operation, 500: Unexpected error}

@endpoint GET /hardware/applications
@desc Gets summarized information about all monitored applications.
@optional {page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page., direction: str(asc/desc)=asc # The sorting order (case insensitive)., sort: str=name # The column to sort by (case insensitive).}
@returns(200) Successful operation
@errors {404: No applications found, 500: Unexpected error}

@endpoint GET /hardware/applications/{applicationId}
@desc Gets detailed information for a specific application.
@required {applicationId: str # The ID of the application.}
@returns(200) Successful operation
@errors {404: No applications found, 500: Unexpected error}

@endpoint GET /hardware/device-monitors/{deviceId}
@desc Gets the Monitors for a specific device.
@required {deviceId: int(int32) # The ID of the device.}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/devices
@desc Gets summarized information about all monitored devices.
@optional {page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page., direction: str(asc/desc)=asc # The sorting order (case insensitive)., sort: str=name # The column to sort by (case insensitive)., groupId: str # The ID of the group., applicationId: str # The ID of the application., serviceId: str # The ID of the service.}
@returns(200) Successful operation
@errors {404: No devices found, 500: Unexpected error}

@endpoint GET /hardware/devices-summary
@desc Gets overall information for all devices.
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/devices/{deviceId}
@desc Gets detailed information about a specific device.
@required {deviceId: int(int32) # The ID of the device.}
@returns(200) Successful operation
@errors {404: No devices found, 500: Unexpected error}

@endpoint GET /hardware/devices/{deviceId}/agent
@desc Gets detailed information about an Agent.
@required {deviceId: int(int32) # The ID of the device.}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/devices/{deviceId}/agent-devices
@desc Gets a list of all the devices monitored by an Agent.
@required {deviceId: int(int32) # The ID of the device.}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/devices/{deviceId}/parameter-history
@desc Gets data history for a parameter of a specific device over a given period.
@required {deviceId: int(int32) # The ID of the device., parameterName: str # The name of the parameter., monitorType: str # The unique name of the Monitor type.}
@optional {from: int(int64) # Beginning of the period (Epoch time, in seconds)., to: int(int64) # End of the period (Epoch time, in seconds)., monitorSid: str # The Monitor SID (to filter the list of Monitors).}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/energy-usage/{deviceId}
@desc Gets the energy usage for a specific device and a given period.
@required {deviceId: int(int32) # The ID of the device.}
@optional {rollPeriod: str(ONE_DAY/ONE_WEEK/ONE_MONTH/SIX_MONTHS/ONE_YEAR)=ONE_DAY # The period for which you wish to retrieve energy usage data., basis: str(MONTHLY/DAILY/HOURLY)=HOURLY # Subdivision of the period for which you wish to retrieve energy usage data.}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/groups
@desc Gets all group summaries.
@optional {page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page., direction: str(asc/desc)=asc # The sorting order (case insensitive)., sort: str=name # The column to sort by (case insensitive).}
@returns(200) Successful operation
@errors {404: No groups found, 500: Unexpected error}

@endpoint GET /hardware/groups/{groupId}
@desc Gets detailed information about a specific group.
@required {groupId: str # The ID of the group.}
@returns(200) Successful operation
@errors {404: No groups found, 500: Unexpected error}

@endpoint PUT /hardware/groups/{groupId}
@desc Updates the values of the energy footprint parameter for a specific group.
@required {groupId: str # The ID of the group.}
@optional {energyCost: num(double) # Updates the electricity rate (unit: $/kWh)., co2Emission: num(double) # Updates the CO<sub>2</sub> emission (unit: kg/kWh)., groupNameFilter: str # Updates the regular expression used to filter the groups for which the power consumption should be reported.}
@returns(200) Successful operation
@errors {404: No settings or groups found, 500: Unexpected error}

@endpoint GET /hardware/heating-margin-devices
@desc Gets the heating margin values for each monitored device, when available.
@optional {covered: bool=True # If set to <em>true</em>, only gets devices whose heating margin information is available.<br>Otherwise, gets any other devices., page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page., direction: str(asc/desc)=asc # The sorting order (case insensitive)., sort: str=name # The column to sort by (case insensitive)., groupId: str # The ID of the group., applicationId: str # The ID of the application., serviceId: str # The ID of the service.}
@returns(200) Successful operation
@errors {404: No devices found, 500: Unexpected error}

@endpoint GET /hardware/history
@desc Gets historical data for a specific group, application or service.
@optional {groupId: str # The ID of the group., applicationId: str # The ID of the application., serviceId: str # The ID of the service., from: int(int64) # Beginning of the period (Epoch time, in seconds)., to: int(int64) # End of the period (Epoch time, in seconds).}
@returns(200) Successful operation
@errors {500: Unexpected error}

@endpoint GET /hardware/search-devices
@desc Searches devices by name, model, manufacturer or serial number.
@required {searchTerms: str # Space-separated search criteria.}
@optional {groupId: str # The ID of the group., applicationId: str # The ID of the application., serviceId: str # The ID of the service., page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page.}
@returns(200) Successful operation
@errors {404: No devices found, 500: Unexpected error}

@endpoint GET /hardware/services
@desc Gets summarized information about all monitored services.
@optional {page: str(int32)=0 # The page number to retrieve (first page is 0)., limit: int(int32)=100 # The maximum number of entries per page., direction: str(asc/desc)=asc # The sorting order (case insensitive)., sort: str=name # The column to sort by (case insensitive).}
@returns(200) Successful operation
@errors {404: No services found, 500: Unexpected error}

@endpoint GET /hardware/services/{serviceId}
@desc Gets detailed information about a specific service.
@required {serviceId: str # The ID of the service.}
@returns(200) Successful operation
@errors {404: No services found, 500: Unexpected error}

@end