{"openapi":"3.0.1","info":{"title":"Labels","description":"Bluestone Labels API - Enables users to manage their organization labels information.\n <b><h1>Deprecated endpoints:</h1></b><table border=\"1px;\"><tr><th style=\"text-align: center; vertical-align: middle;\"><b><h3>Uri</b></h3></th><th><b>Method</b></th><th><b><h3>Since</h3></b></th><th><b><h3>End of life</h3></b></th></tr></table>","version":"1-core"},"servers":[{"url":"api.test.bluestonepim.com/labels","description":"Default Server URL"}],"tags":[{"name":"Labels","description":"To interact with labels."},{"name":"Organization","description":"To interact with organization."}],"paths":{"/labels/{id}":{"get":{"tags":["Labels"],"summary":"Get a label.","operationId":"find","parameters":[{"name":"id","in":"path","description":"Internal identifier for a label to find.","required":true,"schema":{"type":"string"}},{"name":"context","in":"header","description":"Specifies the context in which to operate. If omitted, the default context `en` is used.\n\nIn Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** The default context is identified by the ID `\"en\"`. IDs for additional contexts begin with a lowercase `\"L\"`, **not** with the digit `\"1\"`, followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.","schema":{"type":"string"}},{"name":"context-fallback","in":"header","description":"Specifies whether to enable the fallback mechanism for the context. If omitted, the default value `true` will be used. When set to `true`, the system will provide a default translation or relevant information if the requested context's specific translation is missing.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** Setting the `context-fallback` parameter to `false` disables the fallback mechanism. In this configuration, if a translation or specific context information is not available, the system will not provide an alternative or default content. This ensures that only content that matches the exact context ID requested is returned, potentially leading to cases where no content is available if the specific translation is missing.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelResponse"}}}},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n\nThis response indicates that the requested resource could not be found on the server. It typically occurs when no resource matches the requested URI, or the resource identifier used in the request does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"DETAILS"}]},"put":{"tags":["Labels"],"summary":"Update a label.","description":"Replaces a label's name for one context only - the context given by the context header, or your default context if omitted - leaving that label's names in other contexts unchanged. Fails if the label id does not exist, or if another label already has the same name for that context.","operationId":"update","parameters":[{"name":"id","in":"path","description":"Internal identifier for a label to update.","required":true,"schema":{"type":"string"}},{"name":"context","in":"header","description":"Specifies the context in which to operate. If omitted, the default context `en` is used.\n\nIn Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** The default context is identified by the ID `\"en\"`. IDs for additional contexts begin with a lowercase `\"L\"`, **not** with the digit `\"1\"`, followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelRequest"}}},"required":true},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n\nThis response indicates that the requested resource could not be found on the server. It typically occurs when no resource matches the requested URI, or the resource identifier used in the request does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict\n\nThis response indicates that the request could not be completed due to a conflict with the current state of the target resource. This typically occurs when there are duplicate entries or other data conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"ADD"}]},"delete":{"tags":["Labels"],"summary":"Delete a label.","description":"Permanently deletes a label by id. Fails if the label id does not exist.","operationId":"delete","parameters":[{"name":"id","in":"path","description":"Internal identifier for a label to delete.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found\n\nThis response indicates that the requested resource could not be found on the server. It typically occurs when no resource matches the requested URI, or the resource identifier used in the request does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"DELETE"}]}},"/labels":{"get":{"tags":["Labels"],"summary":"List labels.","description":"Lists labels for the current organization, paginated. Each label's name is resolved to the context given by the context header, or your default context if omitted; if no translation exists in that context, the organization's fallback context is used when context-fallback is enabled, otherwise name is null.","operationId":"list","parameters":[{"name":"page","in":"query","description":"A number sequence representing a block of items to return as a result set.","required":false,"allowEmptyValue":true,"schema":{"minimum":0,"type":"integer","format":"int32","default":0}},{"name":"pageSize","in":"query","description":"Size of a block of items to return. It corresponds with the page parameter.","required":false,"allowEmptyValue":true,"schema":{"maximum":1000,"minimum":1,"type":"integer","format":"int32","default":1000}},{"name":"context","in":"header","description":"Specifies the context in which to operate. If omitted, the default context `en` is used.\n\nIn Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** The default context is identified by the ID `\"en\"`. IDs for additional contexts begin with a lowercase `\"L\"`, **not** with the digit `\"1\"`, followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.","schema":{"type":"string"}},{"name":"context-fallback","in":"header","description":"Specifies whether to enable the fallback mechanism for the context. If omitted, the default value `true` will be used. When set to `true`, the system will provide a default translation or relevant information if the requested context's specific translation is missing.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** Setting the `context-fallback` parameter to `false` disables the fallback mechanism. In this configuration, if a translation or specific context information is not available, the system will not provide an alternative or default content. This ensures that only content that matches the exact context ID requested is returned, potentially leading to cases where no content is available if the specific translation is missing.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListableLabelResponse"}}}},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"LIST"}]},"post":{"tags":["Labels"],"summary":"Create a new label.","description":"Creates a label in the current organization; the created label's id is returned via resourceId, with no response body otherwise. The name is stored only for the context given by the context header, or your default context if omitted - other context are left unset until updated separately. Fails if a label with the same name already exists for that context.","operationId":"create","parameters":[{"name":"context","in":"header","description":"Specifies the context in which to operate. If omitted, the default context `en` is used.\n\nIn Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** The default context is identified by the ID `\"en\"`. IDs for additional contexts begin with a lowercase `\"L\"`, **not** with the digit `\"1\"`, followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelRequest"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict\n\nThis response indicates that the request could not be completed due to a conflict with the current state of the target resource. This typically occurs when there are duplicate entries or other data conflicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"ADD"}]}},"/labels/by-ids":{"post":{"tags":["Labels"],"summary":"List labels by ids.","operationId":"findByIds","parameters":[{"name":"context","in":"header","description":"Specifies the context in which to operate. If omitted, the default context `en` is used.\n\nIn Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** The default context is identified by the ID `\"en\"`. IDs for additional contexts begin with a lowercase `\"L\"`, **not** with the digit `\"1\"`, followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.","schema":{"type":"string"}},{"name":"context-fallback","in":"header","description":"Specifies whether to enable the fallback mechanism for the context. If omitted, the default value `true` will be used. When set to `true`, the system will provide a default translation or relevant information if the requested context's specific translation is missing.\n\nFor more detailed information on how context relates to language settings in Bluestone PIM, refer to the [Languages and Context documentation](https://help.bluestonepim.com/languages-and-context).\n\n**Note:** Setting the `context-fallback` parameter to `false` disables the fallback mechanism. In this configuration, if a translation or specific context information is not available, the system will not provide an alternative or default content. This ensures that only content that matches the exact context ID requested is returned, potentially leading to cases where no content is available if the specific translation is missing.","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelsByIdsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListableLabelResponse"}}}},"400":{"description":"Bad Request\n\nThis response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"oauth2":[]}],"x-bluestone-allowed-user-types":["RESTRICTED","STANDARD"],"x-bluestone-permission":[{"module":"LABELS","accessType":"LIST"}]}}},"components":{"schemas":{"LabelRequest":{"required":["name"],"type":"object","properties":{"name":{"title":"Name of a label.","minLength":1,"type":"string","description":"Text for the label in the context given by the context header, or your default context if omitted. Must be 3-1000 characters and unique among labels in that context."}}},"LabelsByIdsRequest":{"required":["ids"],"type":"object","properties":{"ids":{"maxItems":100,"minItems":0,"type":"array","items":{"type":"string"}}}},"LabelResponse":{"title":"List of results.","type":"object","properties":{"name":{"title":"Name of a label.","type":"string"},"id":{"title":"An identifier randomly generated by PIM. ID is unique across all labels.","type":"string"}}},"ListableLabelResponse":{"type":"object","properties":{"data":{"title":"List of results.","type":"array","items":{"$ref":"#/components/schemas/LabelResponse"}}}},"ErrorResponse":{"type":"object","properties":{"status":{"title":"Error status code.","type":"integer","format":"int32"},"error":{"title":"General error description.","type":"string"},"errorDetails":{"title":"List of errors details.","type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}},"requestId":{"title":"Request ID used for logging.","type":"string"},"timestamp":{"title":"Error timestamp.","type":"integer","format":"int64"},"conflictingEntities":{"title":"Additional entity id list related to error","type":"array","items":{"$ref":"#/components/schemas/ConflictingEntity"}},"quotaLimitExceededDetails":{"title":"Additional details related to quota limit exceeded errors","type":"array","items":{"$ref":"#/components/schemas/LimitExceededDetails"}}}},"ErrorDetails":{"type":"object","properties":{"message":{"title":"Error message.","type":"string"},"field":{"title":"Error related field.","type":"string"},"rejectedValue":{"title":"Invalid value causing error.","type":"string"},"entityId":{"title":"Identifier of the entity related to the error.","type":"string"},"entityType":{"title":"Type of the entity related to the error.","type":"string"}}},"ConflictingEntity":{"type":"object","properties":{"entityId":{"title":"Identifier of the related entity causing the conflict","type":"string"},"entityType":{"title":"Type of the related entity causing the conflict","type":"string"}}},"LimitExceededDetails":{"type":"object","properties":{"message":{"title":"Detailed quota error message","type":"string"},"quota":{"title":"Unique quota identifier","type":"string"},"limit":{"title":"Allowed limit","type":"integer","format":"int32"},"entityId":{"title":"ID of the entity that violated the quota","type":"string","nullable":true},"entityType":{"title":"Type of the entity that violated the quota","type":"string","nullable":true}}}},"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://idp.test.bluestonepim.com/op/token","scopes":{"openid profile systemRoles permissions organization email name nickname":"All needed scopes."}}}}}},"x-amazon-apigateway-api-key-source":"AUTHORIZER"}