# Unit management

Manage Units

## Finding units by filters with sorting and paging

> Retrieves a list of units conforming with the given filters. Supports sorting and paging.\
> \
> \* If the \`Accept-Language\` is set to \`\*\` each internationalized field is returned as a map that contains all of translations in a format of \`key:value\` pairs, where the \`key\` is the language code and \`value\` is the translation.\
> \* The \`Accept-Language\` can contain the priority list of languages which should be returned. Always one language is returned as a single string field. Example: 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7'\
> \* If the \`Accept-Language\` header is empty default language defined in the \`Configuration service\` is taken.\
> \* If the unit name matches none of the specified languages, an empty string is returned in the name field.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"params":{"in":"query","name":"params","required":false,"description":"**Note**: params is not a name of query param. Any API model field can be taken as a filtering parameter.\n\nFiltering can be done by each field available in API. Filtering by multiple fields is also allowed. In that case, fields are aggregated with `AND` logic operator.\n* In a case of string values, the `contains` approach is taken (filtering by substrings). \n* In a case of boolean and number fields, the `equals` approach is taken.\n\nFiltering query params examples:\n* `type=mass` - all units with `type` that contains `mass` are returned. For example, in that case all mass units will be returned.\n* `type=a` - all units with `type` that contains `a` are returned. For example, in that case all `mass` and `distance` units are returned.\n* `factor=1` - all units with `factor` that equals `1` are returned.\n* `baseUnit=true` - all units with `baseUnit` that equals `true` are returned.\n* `type=mass&name=gram` - all units with `type` that contains `mass` AND `name` that contains `gram` are returned. For example, in that case `kilogram`, `gram`, `decagram` units are returned.\n\nFiltering by localized fields:\n* Filtering by localized fields without language key is possible only when `Accept-Language` header with correct language is provided or when it is not set at all (in that case the default language is taken).\nFor example, when `Accept-Language` is set to 'en', the request with parameter `name=meter` returns all units with `name` that contains `meter` in English. For example, in that case `meter`, `kilometer` and `millimeter` units are returned.\n\n* When `Accept-Language` header is set to `*` filtering by localized fields is possible only when fields contains a language key.\nFor example, when `Accept-Language` is set to '*', the request with parameter `name.en=meter` returns all units with `name.en` that contains `meter` in English. For example, in that case `meter`, `kilometer` and `millimeter` units are returned.","schema":{"type":"string"}},"sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by following order of the parameters from left to right.\nCan contain multiple fields in format: `field name`:`sort direction` separated by a comma.\n* The colon with `sort direction` parameter is redundant and descending order is taken only\nif it's equal to `desc` or `DESC`.\n* Ascending order is considered in any other case.\nSorting by `name` parameter works properly only if the `Accept-Language` header is set to\na specific language or is empty with default language specified in the configuration service.","schema":{"type":"string"}},"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}},"accept-language":{"in":"header","name":"Accept-Language","required":false,"description":"The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.","schema":{"type":"string"}},"pageNumber":{"in":"query","name":"pageNumber","required":false,"description":"The page number to be displayed.","schema":{"type":"number"}},"pageSize":{"in":"query","name":"pageSize","required":false,"description":"Number of units on a single page.","schema":{"type":"number","default":60}},"totalCount":{"in":"header","name":"X-Total-Count","required":false,"description":"Total count flag. If set to true, the X-Total-Count header is returned.","schema":{"type":"string"}}},"schemas":{"Unit":{"allOf":[{"$ref":"#/components/schemas/BaseUnit"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/UnitMetadata"}}}]},"BaseUnit":{"type":"object","properties":{"code":{"type":"string","description":"The unit code."},"name":{"description":"The name of the unit in the form of a map (language, value) or string.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"type":{"type":"string","description":"The type of a unit."},"symbol":{"type":"string","description":"The symbol of a unit."},"baseUnit":{"type":"boolean","description":"The base unit flag."},"factor":{"type":"number","description":"The conversion factor. The factor value must be greater than zero."}},"required":["code","name","type","baseUnit","factor"]},"UnitMetadata":{"description":"The metadata of the unit.","properties":{"version":{"type":"integer","description":"The version of the document."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp of the unit creation compliant with the ISO 8601 standard."},"modifiedAt":{"type":"string","format":"date-time","description":"Timestamp of the unit last modification compliant with the ISO 8601 standard."}}},"BadRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."},"details":{"type":"array","description":"Error message details.","items":{"type":"string"}}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"BadRequest400":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest400"}}}},"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units":{"get":{"tags":["Unit management"],"summary":"Finding units by filters with sorting and paging","description":"Retrieves a list of units conforming with the given filters. Supports sorting and paging.\n\n* If the `Accept-Language` is set to `*` each internationalized field is returned as a map that contains all of translations in a format of `key:value` pairs, where the `key` is the language code and `value` is the translation.\n* The `Accept-Language` can contain the priority list of languages which should be returned. Always one language is returned as a single string field. Example: 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7'\n* If the `Accept-Language` header is empty default language defined in the `Configuration service` is taken.\n* If the unit name matches none of the specified languages, an empty string is returned in the name field.","parameters":[{"$ref":"#/components/parameters/params"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/tenant-path"},{"$ref":"#/components/parameters/accept-language"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/totalCount"}],"responses":{"200":{"description":"The units were retrieved successfully.","headers":{"Content-Language":{"description":"The Content-Language response HTTP header defines language(s) of the response body.","schema":{"type":"string"}},"X-Total-Count":{"description":"'The total number of entities in the database matching the specified query criteria.\nReturned if request X-Total-Count header has been set to true.'","schema":{"type":"number"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}}},"400":{"$ref":"#/components/responses/BadRequest400"},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"GET-unit-handling-list-units"}}}}
```

## Adding a new unit

> Creates a new unit. After successful creation, the unit is visible and executable for other parts of the system after 5 minutes.\
> \* If the \`Content-Language\` is set to \`\*\`\
> the request body payload should contain localized fields not as a string,\
> but as a map in format: \`key:value\`, where the \`key\` is the language code and \`value\` is the translation.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["unithandling.unit_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}},"content-language":{"in":"header","name":"Content-Language","required":true,"description":"The Content-Language request HTTP header defines language(s) of the payload.","schema":{"type":"string"}}},"schemas":{"BaseUnit":{"type":"object","properties":{"code":{"type":"string","description":"The unit code."},"name":{"description":"The name of the unit in the form of a map (language, value) or string.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"type":{"type":"string","description":"The type of a unit."},"symbol":{"type":"string","description":"The symbol of a unit."},"baseUnit":{"type":"boolean","description":"The base unit flag."},"factor":{"type":"number","description":"The conversion factor. The factor value must be greater than zero."}},"required":["code","name","type","baseUnit","factor"]},"CreateUnitResponse":{"type":"object","properties":{"code":{"type":"string"}}},"BadRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."},"details":{"type":"array","description":"Error message details.","items":{"type":"string"}}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"Forbidden403":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"Conflict409":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"BadRequest400":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest400"}}}},"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ForbiddenResponse403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden403"}}}},"UnitConflictResponse409":{"description":"The unit already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conflict409"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units":{"post":{"tags":["Unit management"],"summary":"Adding a new unit","description":"Creates a new unit. After successful creation, the unit is visible and executable for other parts of the system after 5 minutes.\n* If the `Content-Language` is set to `*`\nthe request body payload should contain localized fields not as a string,\nbut as a map in format: `key:value`, where the `key` is the language code and `value` is the translation.","parameters":[{"$ref":"#/components/parameters/tenant-path"},{"$ref":"#/components/parameters/content-language"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseUnit"}}}},"responses":{"201":{"description":"The unit has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUnitResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest400"},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"403":{"$ref":"#/components/responses/ForbiddenResponse403"},"409":{"$ref":"#/components/responses/UnitConflictResponse409"},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"POST-unit-handling-create-unit"}}}}
```

## Deleting units in bulk by codes

> Deletes the units with the given codes. After successful deletion, units will not be visible and executable for other parts of the system after 5 minutes.\
> \* The codes are defined in the request body as an array of strings.\
> \* Example: \`\["g", "kg", "dag", "test"]\`

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["unithandling.unit_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}}},"schemas":{"BadRequestNoBody400":{"properties":{"message":{"type":"string","description":"HTTP Status Description."},"_links":{"type":"object","properties":{"self":{"type":"object","properties":{"href":{"type":"string","description":"Link to the requested resource."},"templated":{"type":"boolean","description":"Link template flag."}}}}},"_embedded":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"Description of the error."},"path":{"type":"string","description":"Path associated with the error"}}}}}}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"Forbidden403":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ForbiddenResponse403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden403"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units":{"delete":{"tags":["Unit management"],"summary":"Deleting units in bulk by codes","description":"Deletes the units with the given codes. After successful deletion, units will not be visible and executable for other parts of the system after 5 minutes.\n* The codes are defined in the request body as an array of strings.\n* Example: `[\"g\", \"kg\", \"dag\", \"test\"]`","parameters":[{"$ref":"#/components/parameters/tenant-path"}],"responses":{"204":{"description":"The units have been successfully deleted."},"400":{"description":"The units cannot be deleted due to no payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestNoBody400"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"403":{"$ref":"#/components/responses/ForbiddenResponse403"},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"DELETE-unit-handling-remove-units"}}}}
```

## Retrieving a unit by code

> Retrieves the unit with the given code.\
> \
> \* If the \`Accept-Language\` is set to \`\*\` each internationalized field is returned as a map that contains all of translations in a format of \`key:value\` pairs, where the \`key\` is the language code and \`value\` is the translation.\
> \* The \`Accept-Language\` can contain the priority list of languages which should be returned. Always one language is returned as a single string field.\
> \* If the \`Accept-Language\` header is empty default language defined in the \`Configuration service\` is taken.\
> \* If the unit name matches none of the specified languages, an empty string is returned in the name field.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"unit-code":{"in":"path","name":"unitCode","required":true,"description":"The code of the unit.","schema":{"type":"string"}},"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}},"accept-language":{"in":"header","name":"Accept-Language","required":false,"description":"The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.","schema":{"type":"string"}}},"schemas":{"Unit":{"allOf":[{"$ref":"#/components/schemas/BaseUnit"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/UnitMetadata"}}}]},"BaseUnit":{"type":"object","properties":{"code":{"type":"string","description":"The unit code."},"name":{"description":"The name of the unit in the form of a map (language, value) or string.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"type":{"type":"string","description":"The type of a unit."},"symbol":{"type":"string","description":"The symbol of a unit."},"baseUnit":{"type":"boolean","description":"The base unit flag."},"factor":{"type":"number","description":"The conversion factor. The factor value must be greater than zero."}},"required":["code","name","type","baseUnit","factor"]},"UnitMetadata":{"description":"The metadata of the unit.","properties":{"version":{"type":"integer","description":"The version of the document."},"createdAt":{"type":"string","format":"date-time","description":"Timestamp of the unit creation compliant with the ISO 8601 standard."},"modifiedAt":{"type":"string","format":"date-time","description":"Timestamp of the unit last modification compliant with the ISO 8601 standard."}}},"BadRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."},"details":{"type":"array","description":"Error message details.","items":{"type":"string"}}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"NotFound404":{"properties":{"unitCode":{"type":"string","description":"The code of the requested unit."},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"BadRequest400":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest400"}}}},"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"UnitNotFoundResponse404":{"description":"The unit has not been found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound404"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units/{unitCode}":{"get":{"tags":["Unit management"],"summary":"Retrieving a unit by code","description":"Retrieves the unit with the given code.\n\n* If the `Accept-Language` is set to `*` each internationalized field is returned as a map that contains all of translations in a format of `key:value` pairs, where the `key` is the language code and `value` is the translation.\n* The `Accept-Language` can contain the priority list of languages which should be returned. Always one language is returned as a single string field.\n* If the `Accept-Language` header is empty default language defined in the `Configuration service` is taken.\n* If the unit name matches none of the specified languages, an empty string is returned in the name field.","parameters":[{"$ref":"#/components/parameters/unit-code"},{"$ref":"#/components/parameters/tenant-path"},{"$ref":"#/components/parameters/accept-language"}],"responses":{"200":{"description":"Returns the given unit.","headers":{"Content-Language":{"description":"The Content-Language response HTTP header defines language(s) of the response body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unit"}}}},"400":{"$ref":"#/components/responses/BadRequest400"},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"404":{"$ref":"#/components/responses/UnitNotFoundResponse404"},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"GET-unit-handling-retrieve-unit"}}}}
```

## Updating a unit

> Updates an existing unit. Optimistic locking is applied to prevent update races when unit in\
> the payload contains the optional version field. After successful update, the unit is visible and executable for other parts of the system after 5 minutes.\
> \* If the \`Content-Language\` is set to \`\*\`\
> the request body payload should contain localized fields not as a string,\
> but as a map in format: \`key:value\`, where the \`key\` is the language code and \`value\` is the translation.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["unithandling.unit_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"unit-code":{"in":"path","name":"unitCode","required":true,"description":"The code of the unit.","schema":{"type":"string"}},"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}},"content-language":{"in":"header","name":"Content-Language","required":true,"description":"The Content-Language request HTTP header defines language(s) of the payload.","schema":{"type":"string"}}},"schemas":{"UpdateUnit":{"allOf":[{"$ref":"#/components/schemas/BaseUnit"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/UpdateUnitMetadata"}}}]},"BaseUnit":{"type":"object","properties":{"code":{"type":"string","description":"The unit code."},"name":{"description":"The name of the unit in the form of a map (language, value) or string.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"type":{"type":"string","description":"The type of a unit."},"symbol":{"type":"string","description":"The symbol of a unit."},"baseUnit":{"type":"boolean","description":"The base unit flag."},"factor":{"type":"number","description":"The conversion factor. The factor value must be greater than zero."}},"required":["code","name","type","baseUnit","factor"]},"UpdateUnitMetadata":{"description":"The metadata of the unit.","properties":{"version":{"type":"integer","description":"The version of the document."}}},"BadRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."},"details":{"type":"array","description":"Error message details.","items":{"type":"string"}}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"Forbidden403":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"NotFound404":{"properties":{"unitCode":{"type":"string","description":"The code of the requested unit."},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ForbiddenResponse403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden403"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units/{unitCode}":{"put":{"tags":["Unit management"],"summary":"Updating a unit","description":"Updates an existing unit. Optimistic locking is applied to prevent update races when unit in\nthe payload contains the optional version field. After successful update, the unit is visible and executable for other parts of the system after 5 minutes.\n* If the `Content-Language` is set to `*`\nthe request body payload should contain localized fields not as a string,\nbut as a map in format: `key:value`, where the `key` is the language code and `value` is the translation.","parameters":[{"$ref":"#/components/parameters/unit-code"},{"$ref":"#/components/parameters/tenant-path"},{"$ref":"#/components/parameters/content-language"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUnit"}}}},"responses":{"204":{"description":"The unit has been updated successfully."},"400":{"description":"The unit cannot be updated due to an incorrect payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest400"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"403":{"$ref":"#/components/responses/ForbiddenResponse403"},"404":{"description":"The unit has not been found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound404"}}}},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"PUT-unit-handling-update-unit"}}}}
```

## Deleting a specific unit

> Deletes a unit with a given code. After a successful deletion, the unit is not visible and executable for other parts of the system after 5 minutes.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit management","description":"Manage Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["unithandling.unit_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"unit-code":{"in":"path","name":"unitCode","required":true,"description":"The code of the unit.","schema":{"type":"string"}},"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}}},"responses":{"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ForbiddenResponse403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden403"}}}},"UnitNotFoundResponse404":{"description":"The unit has not been found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound404"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}},"schemas":{"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"Forbidden403":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"NotFound404":{"properties":{"unitCode":{"type":"string","description":"The code of the requested unit."},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}}},"paths":{"/unit-handling/{tenant}/units/{unitCode}":{"delete":{"tags":["Unit management"],"summary":"Deleting a specific unit","description":"Deletes a unit with a given code. After a successful deletion, the unit is not visible and executable for other parts of the system after 5 minutes.","parameters":[{"$ref":"#/components/parameters/unit-code"},{"$ref":"#/components/parameters/tenant-path"}],"responses":{"204":{"description":"The unit has been successfully deleted."},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"403":{"$ref":"#/components/responses/ForbiddenResponse403"},"404":{"$ref":"#/components/responses/UnitNotFoundResponse404"},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"DELETE-unit-handling-remove-unit"}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.