# Segments
Manage segments
## Retrieving all customer segments
> \
> Retrieves all customer segments.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_read","customersegment.segment_read_own"]}],"components":{"securitySchemes":{},"schemas":{"SegmentResponse":{"allOf":[{"$ref":"#/components/schemas/SegmentUpdateBulk"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"SegmentUpdateBulk":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment."}}},{"$ref":"#/components/schemas/SegmentUpdate"}]},"SegmentUpdate":{"allOf":[{"$ref":"#/components/schemas/CommonSegment"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"qParam":{"in":"query","name":"q","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard practises - Query parameter](https://developer.emporix.io/api-references/standard-practices/q-param)\n","schema":{"type":"string"}},"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the pageSize parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."},"acceptLanguage":{"schema":{"type":"string"},"in":"header","name":"Accept-Language","description":"The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism."},"legalEntityId":{"schema":{"type":"string"},"in":"query","name":"legalEntityId","required":false,"description":"The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.\n"},"customerId":{"schema":{"type":"string"},"in":"query","name":"customerId","required":false,"description":"The parameter is utilized for retrieving customer segments for a provided customer.\n\n**NOTE**: This parameter can only be used with `customersegment.segment_read` scope.\n"}}},"paths":{"/customer-segment/{tenant}/segments":{"get":{"summary":"Retrieving all customer segments","tags":["Segments"],"operationId":"GET-customer-segment-retrieve-segments","responses":{"200":{"description":"Customer segments were successfully retrieved.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SegmentResponse"}}}}},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}},"description":"\nRetrieves all customer segments.\n","parameters":[{"$ref":"#/components/parameters/qParam"},{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/xTotalCount"},{"$ref":"#/components/parameters/acceptLanguage"},{"$ref":"#/components/parameters/legalEntityId"},{"$ref":"#/components/parameters/customerId"}]}}}}
```
## Creating a customer segment
> \
> Creates a new customer segment.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"SegmentCreation":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment. It will be auto-generated if not provided."}}},{"$ref":"#/components/schemas/CommonSegment"}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Conflict_409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"contentLanguage":{"schema":{"type":"string"},"in":"header","name":"Content-Language","description":"The Content-Language request HTTP header defines language(s) of the payload."}}},"paths":{"/customer-segment/{tenant}/segments":{"post":{"summary":"Creating a customer segment","tags":["Segments"],"operationId":"POST-customer-segment-create-segment","description":"\nCreates a new customer segment.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentCreation"}}}},"responses":{"201":{"description":"Customer segment was successfully created.","content":{"application/json":{"schema":{"properties":{"id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"409":{"$ref":"#/components/responses/Common_response_Conflict_409"}},"parameters":[{"$ref":"#/components/parameters/contentLanguage"}]}}}}
```
## Searching with parameters for customer segments
> \
> Returns all customer segments that match provided criteria.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_read","customersegment.segment_read_own"]}],"components":{"securitySchemes":{},"schemas":{"SegmentsSearch":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard practises - Query parameter](https://developer.emporix.io/api-references/standard-practices/q-param/)\n"}}},"SegmentResponse":{"allOf":[{"$ref":"#/components/schemas/SegmentUpdateBulk"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"SegmentUpdateBulk":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment."}}},{"$ref":"#/components/schemas/SegmentUpdate"}]},"SegmentUpdate":{"allOf":[{"$ref":"#/components/schemas/CommonSegment"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the pageSize parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."},"acceptLanguage":{"schema":{"type":"string"},"in":"header","name":"Accept-Language","description":"The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism."},"legalEntityId":{"schema":{"type":"string"},"in":"query","name":"legalEntityId","required":false,"description":"The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.\n"},"customerId":{"schema":{"type":"string"},"in":"query","name":"customerId","required":false,"description":"The parameter is utilized for retrieving customer segments for a provided customer.\n\n**NOTE**: This parameter can only be used with `customersegment.segment_read` scope.\n"}}},"paths":{"/customer-segment/{tenant}/segments/search":{"post":{"summary":"Searching with parameters for customer segments","tags":["Segments"],"operationId":"POST-customer-segment-search-segments","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentsSearch"}}}},"responses":{"200":{"description":"Customer segments were successfully retrieved.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SegmentResponse"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}},"description":"\nReturns all customer segments that match provided criteria.\n","parameters":[{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/xTotalCount"},{"$ref":"#/components/parameters/acceptLanguage"},{"$ref":"#/components/parameters/legalEntityId"},{"$ref":"#/components/parameters/customerId"}]}}}}
```
## Retrieving a customer segment
> \
> Retrieves segment with specified ID.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_read","customersegment.segment_read_own"]}],"components":{"securitySchemes":{},"schemas":{"SegmentResponse":{"allOf":[{"$ref":"#/components/schemas/SegmentUpdateBulk"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"SegmentUpdateBulk":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment."}}},{"$ref":"#/components/schemas/SegmentUpdate"}]},"SegmentUpdate":{"allOf":[{"$ref":"#/components/schemas/CommonSegment"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"MetadataResponse":{"allOf":[{"type":"object","properties":{"createdAt":{"description":"The creation date.","type":"string","format":"date-time"},"modifiedAt":{"description":"The modification date.","type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/MetadataUpdate"}]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_NotFound_404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"acceptLanguage":{"schema":{"type":"string"},"in":"header","name":"Accept-Language","description":"The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism."},"legalEntityId":{"schema":{"type":"string"},"in":"query","name":"legalEntityId","required":false,"description":"The parameter is utilized for searching in relation to the legalEntityId. Parameter is only taken into account when customer is assigned to more than one Legal Entity.\n"}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}":{"get":{"summary":"Retrieving a customer segment","tags":["Segments"],"responses":{"200":{"description":"Customer segment successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentResponse"}}}},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/Common_response_NotFound_404"}},"operationId":"GET-customer-segment-retrieve-segment","description":"\nRetrieves segment with specified ID.\n","parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/acceptLanguage"},{"$ref":"#/components/parameters/legalEntityId"}]}}}}
```
## Upserting a customer segment
> \
> Performs the \`UPSERT\` operation. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"SegmentUpdate":{"allOf":[{"$ref":"#/components/schemas/CommonSegment"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Conflict_409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"contentLanguage":{"schema":{"type":"string"},"in":"header","name":"Content-Language","description":"The Content-Language request HTTP header defines language(s) of the payload."}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}":{"put":{"summary":"Upserting a customer segment","tags":["Segments"],"operationId":"PUT-customer-segment-update-segment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentUpdate"}}}},"responses":{"201":{"description":"Customer segment wasn't found. A new customer segment was successfully created.","content":{"application/json":{"schema":{"properties":{"id":{"type":"string"}}}}}},"204":{"description":"Customer segment was successfully updated."},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"409":{"$ref":"#/components/responses/Common_response_Conflict_409"}},"parameters":[{"$ref":"#/components/parameters/contentLanguage"}],"description":"\nPerforms the `UPSERT` operation. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.\n"}}}}
```
## Deleting a customer segment
> \
> Removes segment with specified ID.\
> \
> \*\*Important\*\*: If you want to delete a segment that has items or customers assigned to it, you need to set the \`forceDelete\` query parameter to \`true\`. In this case, all items and customers assignments will be deleted as well.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"parameters":{"forceDelete":{"schema":{"type":"boolean","default":false},"in":"query","name":"forceDelete","required":false,"description":"- If set to `true` and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.\n- If set to `false` or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.\n"}},"responses":{"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}":{"delete":{"summary":"Deleting a customer segment","tags":["Segments"],"parameters":[{"$ref":"#/components/parameters/forceDelete"}],"operationId":"DELETE-customer-segment-remove-segment","responses":{"204":{"description":"Customer segment was successfully deleted."},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}},"description":"\nRemoves segment with specified ID.\n\n**Important**: If you want to delete a segment that has items or customers assigned to it, you need to set the `forceDelete` query parameter to `true`. In this case, all items and customers assignments will be deleted as well.\n"}}}}
```
## Patching a customer segment
> \
> Performs partial update of a segment.\
> \
> The patch request consists of set of operation, that should be defined according to \[RFC-6902]\() standard.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"PatchOperation":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace"],"description":"Indicates an operation which should be done on a return. Available operations: `add` `remove` and `replace`"},"path":{"type":"string","description":"Indicates a path for which the value should be applied. For example:`/mixins/additionalAttributes/externalId`, `/name`, `/status`"},"value":{"oneOf":[{"type":"object"},{"type":"string"},{"type":"number"}],"description":"Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array."}},"required":["op","path"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_NotFound_404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"contentLanguage":{"schema":{"type":"string"},"in":"header","name":"Content-Language","description":"The Content-Language request HTTP header defines language(s) of the payload."}}},"paths":{"/customer-segment/{tenant}/segments/{segmentId}":{"patch":{"summary":"Patching a customer segment","tags":["Segments"],"operationId":"PATCH-customer-segment-update-segment","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PatchOperation"}}}}},"responses":{"204":{"description":"Customer segment was successfully updated."},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"},"404":{"$ref":"#/components/responses/Common_response_NotFound_404"}},"parameters":[{"$ref":"#/components/parameters/contentLanguage"}],"description":"\nPerforms partial update of a segment.\n\nThe patch request consists of set of operation, that should be defined according to [RFC-6902](https://datatracker.ietf.org/doc/html/rfc6902) standard.\n"}}}}
```
## Creating customer segments in bulk
> \
> Creates multiple customer segments. The maximum batch size is 200.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"SegmentCreation":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment. It will be auto-generated if not provided."}}},{"$ref":"#/components/schemas/CommonSegment"}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"BulkResponse":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Item's unique identifier."}}},{"$ref":"#/components/schemas/BulkAssignmentResponse"}]},"BulkAssignmentResponse":{"type":"object","properties":{"index":{"type":"integer","description":"Index of the processed item, matching the item position in request body.\n"},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status description."},"message":{"type":"string","description":"Error message."}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"contentLanguage":{"schema":{"type":"string"},"in":"header","name":"Content-Language","description":"The Content-Language request HTTP header defines language(s) of the payload."}}},"paths":{"/customer-segment/{tenant}/segments/bulk":{"post":{"summary":"Creating customer segments in bulk","tags":["Segments"],"operationId":"POST-customer-segment-create-segments-bulk","description":"\nCreates multiple customer segments. The maximum batch size is 200.\n","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCreation"}}}}},"responses":{"207":{"description":"Multi-status response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BulkResponse"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}},"parameters":[{"$ref":"#/components/parameters/contentLanguage"}]}}}}
```
## Upserting customer segments in bulk
> \
> Performs the \`UPSERT\` operation for multiple customer segments. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.\
> \
> The maximum batch size is 200.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"SegmentUpdateBulk":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the customer segment."}}},{"$ref":"#/components/schemas/SegmentUpdate"}]},"SegmentUpdate":{"allOf":[{"$ref":"#/components/schemas/CommonSegment"},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}}}]},"CommonSegment":{"type":"object","description":"","allOf":[{"type":"object","properties":{"name":{"type":"object","description":"Localized name of the customer segment.","additionalProperties":{"type":"string"}},"description":{"type":"object","description":"Localized description of the customer segment.","additionalProperties":{"type":"string"}},"validity":{"type":"object","description":"Determines the time frame in which the customer segment is valid.","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"status":{"type":"string","description":"Determines whether the customer segment is active or not. If not provided the value is set to `INACTIVE`","enum":["ACTIVE","INACTIVE"]},"siteCode":{"type":"string","description":"Determines for which site the customer segment is available."},"mixins":{"type":"object","description":"A key-value map of additional attributes.","additionalProperties":true}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}}],"required":["name","siteCode"]},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","description":"A key-value map, where key is a mixin name and value is a link to the mixin schema.","additionalProperties":true}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"type":"integer","description":"The document version number."}}},{"$ref":"#/components/schemas/MetadataCreate"}]},"BulkResponse":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Item's unique identifier."}}},{"$ref":"#/components/schemas/BulkAssignmentResponse"}]},"BulkAssignmentResponse":{"type":"object","properties":{"index":{"type":"integer","description":"Index of the processed item, matching the item position in request body.\n"},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status description."},"message":{"type":"string","description":"Error message."}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"contentLanguage":{"schema":{"type":"string"},"in":"header","name":"Content-Language","description":"The Content-Language request HTTP header defines language(s) of the payload."}}},"paths":{"/customer-segment/{tenant}/segments/bulk":{"put":{"summary":"Upserting customer segments in bulk","tags":["Segments"],"operationId":"PUT-customer-segment-update-segments-bulk","description":"\nPerforms the `UPSERT` operation for multiple customer segments. If a segment with specified ID exists in the system, then it is updated. If it doesn't exist, a new customer segment is created.\n\nThe maximum batch size is 200.\n","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SegmentUpdateBulk"}}}}},"responses":{"207":{"description":"Multi-status response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BulkResponse"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}},"parameters":[{"$ref":"#/components/parameters/contentLanguage"}]}}}}
```
## Deleting customer segments in bulk
> \
> Removes multiple customer segments. The maximum batch size is 200.\
> \
> \### The IDs of customer segments for deletion should be defined in the request body as an array of strings.\
> \#### Example: \`\["firstId", "secondId", "thirdId"]\`\
> \
> \
> \*\*Important\*\*: If you want to delete a segment that has items or customers assigned to it, you need to set the \`forceDelete\` query parameter to \`true\`. In this case, all items and customers assignments will be deleted as well.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"parameters":{"forceDelete":{"schema":{"type":"boolean","default":false},"in":"query","name":"forceDelete","required":false,"description":"- If set to `true` and the segment has items or customers assigned to it, both the segment and the segment assignments will be deleted.\n- If set to `false` or not specified and the segment has items or customers assigned to it, the endpoint will respond with the 400 error.\n"}},"schemas":{"BulkResponse":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Item's unique identifier."}}},{"$ref":"#/components/schemas/BulkAssignmentResponse"}]},"BulkAssignmentResponse":{"type":"object","properties":{"index":{"type":"integer","description":"Index of the processed item, matching the item position in request body.\n"},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status description."},"message":{"type":"string","description":"Error message."}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/bulk":{"delete":{"summary":"Deleting customer segments in bulk","tags":["Segments"],"operationId":"DELETE-customer-segment-remove-segments-bulk","parameters":[{"$ref":"#/components/parameters/forceDelete"}],"description":"\nRemoves multiple customer segments. The maximum batch size is 200.\n\n### The IDs of customer segments for deletion should be defined in the request body as an array of strings.\n#### Example: `[\"firstId\", \"secondId\", \"thirdId\"]`\n\n\n**Important**: If you want to delete a segment that has items or customers assigned to it, you need to set the `forceDelete` query parameter to `true`. In this case, all items and customers assignments will be deleted as well.\n","responses":{"207":{"description":"Multi-status response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BulkResponse"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}}}}}}
```
## Checking which items belong to segment
> \
> \
> Checks if the provided items match specified criteria - if ids of the products are assigned directly to one of the provided segments or indirectly through the category assignment. Only items assigned to the active segments will be returned.
```json
{"openapi":"3.0.0","info":{"title":"Customer Segment Service","version":"0.0.1"},"tags":[{"name":"Segments","description":"Manage segments"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"CustomerAccessToken":["customersegment.segment_manage"]}],"components":{"securitySchemes":{},"schemas":{"Match":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MatchItem"}},"segmentIds":{"type":"array","items":{"type":"string"}},"site":{"type":"string"}},"required":["items","segmentIds","site"]},"MatchItem":{"type":"object","properties":{"id":{"type":"string","description":"Id of the product."}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Error message."},"resourceId":{"type":"string","description":"An ID of the resource which caused the error."},"details":{"type":"object","description":"Error details","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}}},"responses":{"Common_response_BadRequest_400":{"description":"Bad request due to validation, incorrect parameters, etc.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Common_response_Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Common_response_Forbidden_403":{"description":"Access forbidden. The caller is not allowed to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/customer-segment/{tenant}/segments/match":{"post":{"summary":"Checking which items belong to segment","tags":["Segments"],"operationId":"POST-customer-segment-check-match","description":"\n\nChecks if the provided items match specified criteria - if ids of the products are assigned directly to one of the provided segments or indirectly through the category assignment. Only items assigned to the active segments will be returned.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Match"}}}},"responses":{"200":{"description":"Id of the products which match criteria.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MatchItem"}}}}},"400":{"$ref":"#/components/responses/Common_response_BadRequest_400"},"401":{"$ref":"#/components/responses/Common_response_Unauthorized_401"},"403":{"$ref":"#/components/responses/Common_response_Forbidden_403"}}}}}}
```
---
# 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/companies-and-customers/customer-segments/api-reference/segments.md?ask=
```
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.