openapi: 3.2.0 info: version: 2.6.11 title: HERE Tracking Rules API description: 'HERE Tracking is a cloud product designed to address location tracking problems for a wide range of Location IoT industry verticals. HERE Tracking also includes end-user mobile and web applications that can be used to demonstrate the product.' license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://tracking.hereapi.com/ - url: https://tracking.api.here.com/ tags: - description: The Rules service creates and manages rules. name: Rules paths: /rules/v4/health: get: summary: Gets service health security: [] responses: '200': description: 'OK The service is performing as expected ' content: application/json: schema: type: object properties: message: type: string description: Health status example: message: healthy '500': description: 'Service unavailable The service is not performing as expected ' tags: - Rules operationId: getRulesV4Health x-operation-id-source: derived /rules/v4/version: get: summary: Gets service version security: [] responses: '200': description: 'Success ' content: application/json: schema: description: "OK\nService returns its current version number\nschema:\n type: object\n properties:\n \"service-name\":\n type: string\n description: Version of service\n example:\n servicename: \"1.0.0\"\n" '500': description: 'Service unavailable The service is not performing as expected ' tags: - Rules operationId: getRulesV4Version x-operation-id-source: derived /rules/v4: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: projectId schema: type: string minLength: 1 maxLength: 50 description: 'Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the `projectId` query parameter needs to be specified explicitly. ' in: query required: false post: summary: Creates a rule description: 'Creates a rule of the specified rule `type` and with the defined `threshold`. After the rule has been created, it needs to be associated to a device to get activated. Detention rule --- For a rule of the `detention` type the threshold is defined as a duration in seconds. A `DETENTION_STARTED` event gets triggered when the device has remained stationary for longer than the threshold duration. A `DETENTION_ENDED` event will be generated when the device starts moving again. Utilization rule --- For a rule of the `utilization` type the threshold is defined as a duration in seconds. An `UNUTILIZED` event will be generated when the device has been stationary for longer than the threshold duration, and `UTILIZED` event gets triggered when the device starts moving again after having been stationary. Dwelling rule --- For a rule of the `dwelling` type the threshold is defined as a duration in seconds. A `DWELLING_STARTED` event gets triggered when a dwelling time of the device inside any device-associated geofence exceeds the threshold duration. When the device exits the geofence, a `DWELLING_ENDED` event will be generated. Online rule --- For a rule of the `online` type there is no threshold defined. A `TRUE_TO_FALSE` event gets triggered when the device is late for the planned ingestion schedule by more than 5 minutes. A `FALSE_TO_TRUE` event is generated when the device starts ingesting again after having been offline. The planned ingestion schedule needs to be configured in the device `desired shadow` (the `desired.system.powerSave.sendMs` or `desired.system.rate.sendMs` property). Stock rule --- For a rule of the `stock` type the threshold is defined as `minVolume` and/or `maxVolume` values. When creating a stock rule, also a geofence ID needs to be specified. When the number of devices inside the specified geofence exceeds `maxVolume`, an `OVERSTOCK` event will be generated. Similarly, when the number of devices inside the specified geofence gets below `minVolume`, an `UNDERSTOCK` event will be generated. When the number of devices inside the specified geofence is between `minVolume` and `maxVolume`, a `NORMAL_VOLUME` event will be generated. Note that the stock rule only gets triggered for devices that are associated to the specified geofence. There can be up to 10 stock rules in a tracking project. Shipment estimate change --- For a rule of the `shipmentEtaChange` type the threshold is defined as a ETD/ETA estimation deviation in seconds. A `SHIPMENT_ESTIMATE_CHANGED` event gets triggered when the new ETD/ETA estimates values differ from the previous estimates more than the defined threshold. If the `segmentEtaChange` property is set to `true`, then the event is triggered from segment level ETD/ETA estimate changes, not from shipment level ETD/ETA estimate changes. Shipment schedule rule --- For a rule of the `shipmentSchedule` type there are `before` and `after` deviation time thresholds from the planned shipment ETD/ETA. A `SHIPMENT_EARLY` event gets triggered when the shipment is ahead of schedule by the number of `before` seconds. A `SHIPMENT_DELAYED` event gets triggered when the shipment is behind schedule by the number of `after` seconds. A `SHIPMENT_ON_TIME` event gets triggered when the shipment is on time. When a rule has been successfully created, the response body will contain the created rule ID.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: oneOf: - title: Detention type: object properties: type: type: string description: The rule type enum: - detention threshold: description: 'Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Dwelling type: object properties: type: type: string description: The rule type enum: - dwelling threshold: description: 'Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Online type: object properties: type: type: string description: The rule type enum: - online name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type additionalProperties: false - title: Shipment ETD/ETA change type: object properties: type: type: string description: The rule type enum: - shipmentEtaChange threshold: type: object properties: deviation: type: integer description: 'Shipment ETA change event is triggered if shipment ETD or ETA changes more than deviation seconds. If `segmentEtaChange` is set to `true` event is triggered if segment ETD or ETA changes more than deviation seconds. ' minimum: 600 maximum: 2147483647 segmentEtaChange: type: boolean description: 'If set to `true` the event is triggered from segment level ETD/ETA changes, otherwise from shipment level ETD/ETA changes. Default is `false`. ' required: - deviation additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Shipment Schedule type: object properties: type: type: string description: The rule type enum: - shipmentSchedule threshold: type: object properties: before: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule minimum: 0 maximum: 2147483647 after: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule minimum: 0 maximum: 2147483647 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Stock type: object properties: type: type: string description: The rule type enum: - stock geofenceId: description: Geofence ID type: string format: uuid threshold: type: object properties: maxVolume: type: integer description: A maximum volume of stock minimum: 0 minVolume: type: integer description: A minimum volume of stock minimum: 0 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - geofenceId - threshold additionalProperties: false - title: Utilization type: object properties: type: type: string description: The rule type enum: - utilization threshold: description: 'Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false tags: - Rules responses: '201': description: 'Created The rule was successfully created. ' content: application/json: schema: type: object properties: ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - ruleId '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' operationId: postRulesV4 x-operation-id-source: derived get: summary: Gets all rules description: Gets all rules definitions. security: - UserToken: [] - ClientToken: [] parameters: - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: limit description: The number of items to return per page schema: type: integer minimum: 1 maximum: 100 default: 100 in: query required: false tags: - Rules responses: '200': description: 'Response body contains an array of rule objects, `count` indicates the number of returned rules, and `pageToken` is the next page token if available. If no rules are found, an object with an empty data array is returned. ' content: application/json: example: items: - ruleId: f4c26630-5d26-4cd1-a57e-g7834e72cb99 rule: type: dwelling threshold: durationS: 3600 nextPageToken: 024ggjjea253d79fc count: 1 limit: 100 schema: type: object properties: limit: description: Maximum number of items as specified in request type: integer minimum: 1 maximum: 100 count: description: Number of items returned in the response type: integer minimum: 0 maximum: 100 nextPageToken: description: Token to fetch the next page (if exists) type: string items: type: array items: type: object properties: ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' rule: oneOf: - title: Detention type: object properties: type: type: string description: The rule type enum: - detention threshold: description: 'Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Dwelling type: object properties: type: type: string description: The rule type enum: - dwelling threshold: description: 'Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Online type: object properties: type: type: string description: The rule type enum: - online name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type additionalProperties: false - title: Shipment ETD/ETA change type: object properties: type: type: string description: The rule type enum: - shipmentEtaChange threshold: type: object properties: deviation: type: integer description: 'Shipment ETA change event is triggered if shipment ETD or ETA changes more than deviation seconds. If `segmentEtaChange` is set to `true` event is triggered if segment ETD or ETA changes more than deviation seconds. ' minimum: 600 maximum: 2147483647 segmentEtaChange: type: boolean description: 'If set to `true` the event is triggered from segment level ETD/ETA changes, otherwise from shipment level ETD/ETA changes. Default is `false`. ' required: - deviation additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Shipment Schedule type: object properties: type: type: string description: The rule type enum: - shipmentSchedule threshold: type: object properties: before: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule minimum: 0 maximum: 2147483647 after: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule minimum: 0 maximum: 2147483647 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Stock type: object properties: type: type: string description: The rule type enum: - stock geofenceId: description: Geofence ID type: string format: uuid threshold: type: object properties: maxVolume: type: integer description: A maximum volume of stock minimum: 0 minVolume: type: integer description: A minimum volume of stock minimum: 0 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - geofenceId - threshold additionalProperties: false - title: Utilization type: object properties: type: type: string description: The rule type enum: - utilization threshold: description: 'Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false required: - ruleId - rule required: - limit - count - items additionalProperties: false '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' operationId: getRulesV4 x-operation-id-source: derived delete: summary: Deletes all rules description: 'Deletes all rules of the project. Note that one needs to supply an HTTP header `x-confirm` with the value `true` to force the deletion. If the header is not provided, the request will fail.' security: - UserToken: [] - ClientToken: [] tags: - Rules parameters: - schema: type: string enum: - 'true' in: header name: x-confirm required: true description: 'A safety measure that prevents one from accidentally deleting data. To confirm that all entries should be deleted, set the value to `true`. ' responses: '204': description: 'Successful (no content) All rule definitions were successfully deleted. ' '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' operationId: deleteRulesV4 x-operation-id-source: derived /rules/v4/{ruleId}: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - in: path schema: type: string format: uuid description: 'Must be a valid UUIDv4. ' name: ruleId description: ID of the rule required: true get: summary: Gets a single rule description: Gets details of a single rule identified by the `ruleId`. security: - UserToken: [] - ClientToken: [] tags: - Rules responses: '200': description: 'Response body contains a single rule object. ' content: application/json: example: ruleId: f4c26630-5d26-4cd1-a57e-g7834e72cb99 rule: type: dwelling threshold: durationS: 3600 schema: type: object properties: ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' rule: oneOf: - title: Detention type: object properties: type: type: string description: The rule type enum: - detention threshold: description: 'Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Dwelling type: object properties: type: type: string description: The rule type enum: - dwelling threshold: description: 'Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Online type: object properties: type: type: string description: The rule type enum: - online name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type additionalProperties: false - title: Shipment ETD/ETA change type: object properties: type: type: string description: The rule type enum: - shipmentEtaChange threshold: type: object properties: deviation: type: integer description: 'Shipment ETA change event is triggered if shipment ETD or ETA changes more than deviation seconds. If `segmentEtaChange` is set to `true` event is triggered if segment ETD or ETA changes more than deviation seconds. ' minimum: 600 maximum: 2147483647 segmentEtaChange: type: boolean description: 'If set to `true` the event is triggered from segment level ETD/ETA changes, otherwise from shipment level ETD/ETA changes. Default is `false`. ' required: - deviation additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Shipment Schedule type: object properties: type: type: string description: The rule type enum: - shipmentSchedule threshold: type: object properties: before: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule minimum: 0 maximum: 2147483647 after: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule minimum: 0 maximum: 2147483647 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Stock type: object properties: type: type: string description: The rule type enum: - stock geofenceId: description: Geofence ID type: string format: uuid threshold: type: object properties: maxVolume: type: integer description: A maximum volume of stock minimum: 0 minVolume: type: integer description: A minimum volume of stock minimum: 0 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - geofenceId - threshold additionalProperties: false - title: Utilization type: object properties: type: type: string description: The rule type enum: - utilization threshold: description: 'Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false required: - ruleId - rule '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: No rules with the provided ruleId were found details: hereErrorCode: 404306 description: No rules with the provided ruleId were found operationId: getRulesV4ByRuleId x-operation-id-source: derived put: summary: Updates a single rule description: 'Updates the name, description and threshold of the rule `ruleId`. The rule type cannot be updated. If some of the these properties are not provided in the request body, their values will be set to null. If the rule has been updated successfully, the response will contain the updated rule details.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: oneOf: - title: Detention type: object properties: type: type: string description: The rule type enum: - detention threshold: description: 'Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Dwelling type: object properties: type: type: string description: The rule type enum: - dwelling threshold: description: 'Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Online type: object properties: type: type: string description: The rule type enum: - online name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type additionalProperties: false - title: Shipment ETD/ETA change type: object properties: type: type: string description: The rule type enum: - shipmentEtaChange threshold: type: object properties: deviation: type: integer description: 'Shipment ETA change event is triggered if shipment ETD or ETA changes more than deviation seconds. If `segmentEtaChange` is set to `true` event is triggered if segment ETD or ETA changes more than deviation seconds. ' minimum: 600 maximum: 2147483647 segmentEtaChange: type: boolean description: 'If set to `true` the event is triggered from segment level ETD/ETA changes, otherwise from shipment level ETD/ETA changes. Default is `false`. ' required: - deviation additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Shipment Schedule type: object properties: type: type: string description: The rule type enum: - shipmentSchedule threshold: type: object properties: before: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule minimum: 0 maximum: 2147483647 after: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule minimum: 0 maximum: 2147483647 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Stock type: object properties: type: type: string description: The rule type enum: - stock geofenceId: description: Geofence ID type: string format: uuid threshold: type: object properties: maxVolume: type: integer description: A maximum volume of stock minimum: 0 minVolume: type: integer description: A minimum volume of stock minimum: 0 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - geofenceId - threshold additionalProperties: false - title: Utilization type: object properties: type: type: string description: The rule type enum: - utilization threshold: description: 'Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false tags: - Rules responses: '200': description: 'Successful The rule was updated. ' content: application/json: schema: type: object properties: ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' rule: oneOf: - title: Detention type: object properties: type: type: string description: The rule type enum: - detention threshold: description: 'Detention event is triggered when the asset has been continuously stationary for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Dwelling type: object properties: type: type: string description: The rule type enum: - dwelling threshold: description: 'Dwelling event is triggered when the asset has been continuously inside a geofence for longer than the threshold duration. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Online type: object properties: type: type: string description: The rule type enum: - online name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type additionalProperties: false - title: Shipment ETD/ETA change type: object properties: type: type: string description: The rule type enum: - shipmentEtaChange threshold: type: object properties: deviation: type: integer description: 'Shipment ETA change event is triggered if shipment ETD or ETA changes more than deviation seconds. If `segmentEtaChange` is set to `true` event is triggered if segment ETD or ETA changes more than deviation seconds. ' minimum: 600 maximum: 2147483647 segmentEtaChange: type: boolean description: 'If set to `true` the event is triggered from segment level ETD/ETA changes, otherwise from shipment level ETD/ETA changes. Default is `false`. ' required: - deviation additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Shipment Schedule type: object properties: type: type: string description: The rule type enum: - shipmentSchedule threshold: type: object properties: before: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is ahead of schedule minimum: 0 maximum: 2147483647 after: type: integer description: Allowed time deviation in seconds from the planned ETD/ETA in case the shipment is behind the schedule minimum: 0 maximum: 2147483647 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false - title: Stock type: object properties: type: type: string description: The rule type enum: - stock geofenceId: description: Geofence ID type: string format: uuid threshold: type: object properties: maxVolume: type: integer description: A maximum volume of stock minimum: 0 minVolume: type: integer description: A minimum volume of stock minimum: 0 additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - geofenceId - threshold additionalProperties: false - title: Utilization type: object properties: type: type: string description: The rule type enum: - utilization threshold: description: 'Utilization event is triggered when the asset starts moving indicating that the asset is utilized, and also when the asset stops moving and has been stationary for longer than the threshold duration indicating that the asset is unutilized. ' type: object properties: durationS: type: integer description: Duration in seconds minimum: 0 maximum: 2147483647 required: - durationS additionalProperties: false name: type: string maxLength: 50 description: Rule name description: type: string maxLength: 1000 description: Rule description required: - type - threshold additionalProperties: false required: - ruleId - rule '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: No rules with the provided ruleId were found details: hereErrorCode: 404306 description: No rules with the provided ruleId were found operationId: putRulesV4ByRuleId x-operation-id-source: derived delete: summary: Deletes a rule description: Deletes a rule identified by the `ruleId`. security: - UserToken: [] - ClientToken: [] tags: - Rules responses: '204': description: Successful (no content) '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee message: No rules with the provided ruleId were found details: hereErrorCode: 404306 description: No rules with the provided ruleId were found '409': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Conflict code: 409 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource already exists. details: hereErrorCode: 404306 description: 'Conflict The specified resource already exists ' operationId: deleteRulesV4ByRuleId x-operation-id-source: derived components: securitySchemes: ApiKey: type: apiKey in: query name: apiKey description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity & Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html). ' Bearer: type: http scheme: bearer bearerFormat: JWT description: "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nUsers are authenticated using an OAuth 1.0 bearer token obtained using the `/users/v2/login` endpoint.\n\nDevices are authenticated using an OAuth 1.0 bearer token obtained using the `/v2/token` endpoint.\n\n**Make a request using the bearer token for authentication**\n\nMake a request with an `Authorization` header containing the obtained bearer token.\n\nExample:\n\n```\n Authorization: Bearer h1.yxPIksZ0ViLq77f1Nh-9cg.NVgGBZVlCU8G7kjV_...\n```\n\n> **Note:** For the available authentication options, see the [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html).\n" UserToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using user's realm, username and password and then further scoped to a specific project.\n\nFirst obtain access token from [/users/v2/login endpoint](#tag/Users/paths/~1users~1v2~1login/post).\nThen use [/users/v2/tokenExchange endpoint](#tag/Users/paths/~1users~1v2~1tokenExchange/post) to convert\nyour user access token into a project-scoped user access token.\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.xikjhDyJsE17VLhPXiu.fm3WsNOunstXH78RvU8_...\n```\n" ClientToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using application's OAuth 2.0 credentials (key + secret) and then scoped to a specific project.\n\nFollow [instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html)\nto create your application credentials and obtain the token using OLP CLI. With an exception\nthat when getting the token you need to provide also project's HRN value:\n\n```\n olp api token get --scope {PROJECT_HRN}\n```\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.PGEVzQmaoW5pyBYUlWu.SQoSCF7qpToEFMHgSlJ_...\n```\n" DeviceToken: type: http scheme: bearer bearerFormat: JWT description: 'This access token is obtained from [/v2/token endpoint](#tag/Ingestion/paths/~1v2~1token/post) using a signed request. > **Note:** Only a small subset of our endpoints support this token type and is only useful for hardware devices. > You probably won''t need this. ' signedRequest: type: http scheme: oauth description: "HERE Tracking requires that you sign your requests for tokens. The signature method uses the OAuth 1.0 standard. For more information on this standard, see the [OAuth Core 1.0](https://oauth.net/core/1.0/) specification.\n\n> **Note:** You must create a new signature for each token request to HERE Tracking. Signatures can only be used once.\n\n**Create the Signature Base String**\n\nThe first step in creating a signature is to create the signature base string. This string contains the parameters to use when generating the signature.\n\n*1. To begin, make sure you have the information listed in the following table.*\n\n| Parameter | Description |\n| ------------------------ | -----------------------------------------|\n| oauth\\_consumer\\_key | The device ID for which you want to generate a token. |\n| oauth\\_signature\\_method | Always use \"HMAC-SHA256\". |\n| oauth\\_timestamp | The number of seconds since the Unix epoch at the point the request is generated. This must be within 10 seconds of the timestamp returned by the `/v2/timestamp` endpoint. |\n| oauth\\_nonce | A unique string for this signature. The string cannot have been used in a previous signature. Each token generation request to HERE Tracking must have a unique signature, and the value in this parameter is what is used to ensure the signature is unique. |\n| oauth\\_version | Always use \"1.0\". |\n\n*2. Combine these values into a single string by following these steps:*\n\n 1. URL encode every key and value.\n 2. Sort the list of key-value pairs alphabetically by key.\n 3. Concatenate each key/value pair, separating each with an ampersand character (\"&\").\n\nThe result is a parameter string that looks like this (line breaks are added for legibility):\n\n ```\n oauth_consumer_key=47164fb0-b7b3-49e8-891b-650270b82cf2\n &oauth_nonce=LIIpk4\n &oauth_signature_method=HMAC-SHA256\n &oauth_timestamp=1513634609\n &oauth_version=1.0\n ```\n\n*3. Combine the HTTP method, base URL, and parameter string into a single string called the \"base string\". This will be the string from which the signature is generated. The base string is in this format:*\n\n ```\n POST&https://tracking.api.here.com/v2/token&\n ```\n\n The base string consists of:\n\n 1. The HTTP method in caps (POST) followed by an ampersand (\"&\")\n 2. The URL of the HERE Tracking token endpoint followed by an ampersand (\"&\")\n 3. The URL-encoded parameter string.\n\n For example (line breaks are added for legibility):\n\n ```\n POST\n &https%3A%2F%2Ftracking.api.here.com%2Fv2%2Ftoken\n &oauth_consumer_key%3D47164fb0-b7b3-49e8-891b-650270b82cf2%26\n oauth_nonce%3DLIIpk4%26oauth_signature_method%3DHMAC-SHA256%26\n oauth_timestamp%3D1513634609%26oauth_version%3D1.0\n ```\n\n > **Note:** The URL-encoded base string should contain exactly two ampersands (\"&\").\n\n**Create the signature**\n\nThe signing key used to sign the base string is the `deviceSecret` followed by an ampersand (\"&\").\n\nCreate the signature by passing the signature base string and the signing key to the `HMAC-SHA256` hashing algorithm and converting the result to a `base64` string. Then, use the signature to request a token.\n\n**Request the token**\n\nMake a `POST` request to this endpoint with an `Authorization` header constructed from the above parameters and the generated signature.\n\nExample:\n\n```\n Authorization: OAuth oauth_consumer_key=\"47164fb0-b7b3-49e8-891b-650270b82cf2\",\n oauth_signature_method=\"HMAC-SHA256\",\n oauth_timestamp=\"1513634609\",\n oauth_nonce=\"LIIpk4\",\n oauth_version=\"1.0\",\n oauth_signature=\"pQ9EJX14L736B%2Br7uZl4yQlO6Xw%3D\"\n```\n" externalDocs: description: The Developer guide and Release notes are available here. url: https://www.here.com/docs/bundle/tracking-api-developer-guide