# Retrieve entities using a query string

Lists entities that match the query in a request body.  The Querying API supports various [operators](#tag/querying) for filter types that use an `operator` field. Relation filters do not support operators.  The query filter supports multiple types, each with specific properties.   The Querying API V3 does not support the `fulltext` filter. #### Composite filter
Combines multiple filters using a logical operator (`AND`, `OR`).
- Required - `type`, `operator`, `children`
- Example - `{"type": "Composite", "operator": "AND", "children": [...]}`

#### Not filter
Negates a child filter.
- Required - `type`, `child`
- Example - `{"type": "Not", "child": {"type": "Definition", "operator": "Equals", "name": "M.Asset"}}`

#### Property filter
Filters entities by a property value.
- Required - `type`, `property`, `operator`, `value`, `data_type`
- Optional - `culture` (for localized properties)
- Valid `data_type` values - `String`, `Int`, `Long`, `Decimal`, `Float`, `DateTime`, `DateTimeOffset`, `Bool`
- Example - `{"type": "Property", "property": "Title", "operator": "Contains", "value": "example", "data_type": "String"}`

#### Relation filter
Filters entities by a relation. The `operator` field is not applicable to Relation filters. If included, it will be ignored and will not affect query results. For a detailed example, see [Relations](https://doc.sitecore.com/ch/en/developers/cloud-dev/relations.html).
- Required - `type`, `relation`
- Optional - `parent_id` or `child_id`
- Example - `{"type": "Relation", "relation": "FinalLifeCycleStatusToAsset", "parent_id": 543}`

#### CreatedBy filter
Filters entities by the user who created them.
- Required - `type`, `user_id`
- Example - `{"type": "CreatedBy", "user_id": 123}`

#### ModifiedBy filter
Filters entities by the user who last modified them.
- Required - `type`, `user_id`
- Example - `{"type": "ModifiedBy", "user_id": 456}`

#### SecuredAncestors filter
Filters entities by their secured ancestor.
- Required - `type`, `ancestor_id`
- Example - `{"type": "SecuredAncestors", "ancestor_id": 789}`

#### ID filter
Filters entities by their ID.
- Required - `type`, `operator`, `value`
- Example - `{"type": "Id", "operator": "Equals", "value": 12345}`

#### Identifier filter
Filters entities by their identifier.
- Required - `type`, `operator`, `value`
- Example - `{"type": "Identifier", "operator": "Equals", "value": "my-unique-identifier"}`

#### Definition filter
Filters entities by their entity definition.
- Required - `type`, `operator`, `name`
- Example - `{"type": "Definition", "operator": "Equals", "name": "M.Asset"}`

#### Modules filter
Filters entities by the modules they belong to.
- Required - `type`, `modules`
- Example - `{"type": "Modules", "modules": ["M.DAM", "M.PCM"]}`

#### CreatedOn filter
Filters entities by their creation date.
- Required - `type`, `operator`, `value` (ISO 8601 format)
- Example - `{"type": "CreatedOn", "operator": "GreaterThan", "value": "2024-01-01T00:00:00Z"}`

#### ModifiedOn filter
Filters entities by their last modification date.
- Required - `type`, `operator`, `value` (ISO 8601 format)
- Example - `{"type": "ModifiedOn", "operator": "LessThan", "value": "2024-12-31T23:59:59Z"}`

Endpoint: POST /api/entities/query
Version: v3.0
Security: OAuth2.0

## Description:

  - `Not filter` ()
    Negates a child filter. Required - type, childExample - {"type": "Not", "child": {"type": "Definition", "operator": "Equals", "name": "M.Asset"}}

  - `Property filter` ()
    Filters entities by a property value. Required - type, property, operator, value, data_typeOptional - culture (for localized properties)Valid data_type values - String, Int, Long, Decimal, Float, DateTime, DateTimeOffset, BoolExample - {"type": "Property", "property": "Title", "operator": "Contains", "value": "example", "data_type": "String"}

  - `Relation filter` ()
    Filters entities by a relation. The operator field is not applicable to Relation filters. If included, it will be ignored and will not affect query results. For a detailed example, see Relations. Required - type, relationOptional - parent_id or child_idExample - {"type": "Relation", "relation": "FinalLifeCycleStatusToAsset", "parent_id": 543}

  - `CreatedBy filter` ()
    Filters entities by the user who created them. Required - type, user_idExample - {"type": "CreatedBy", "user_id": 123}

  - `ModifiedBy filter` ()
    Filters entities by the user who last modified them. Required - type, user_idExample - {"type": "ModifiedBy", "user_id": 456}

  - `SecuredAncestors filter` ()
    Filters entities by their secured ancestor. Required - type, ancestor_idExample - {"type": "SecuredAncestors", "ancestor_id": 789}

  - `ID filter` ()
    Filters entities by their ID. Required - type, operator, valueExample - {"type": "Id", "operator": "Equals", "value": 12345}

  - `Identifier filter` ()
    Filters entities by their identifier. Required - type, operator, valueExample - {"type": "Identifier", "operator": "Equals", "value": "my-unique-identifier"}

  - `Definition filter` ()
    Filters entities by their entity definition. Required - type, operator, nameExample - {"type": "Definition", "operator": "Equals", "name": "M.Asset"}

  - `Modules filter` ()
    Filters entities by the modules they belong to. Required - type, modulesExample - {"type": "Modules", "modules": ["M.DAM", "M.PCM"]}

  - `CreatedOn filter` ()
    Filters entities by their creation date. Required - type, operator, value (ISO 8601 format)Example - {"type": "CreatedOn", "operator": "GreaterThan", "value": "2024-01-01T00:00:00Z"}

  - `ModifiedOn filter` ()
    Filters entities by their last modification date. Required - type, operator, value (ISO 8601 format)Example - {"type": "ModifiedOn", "operator": "LessThan", "value": "2024-12-31T23:59:59Z"}

## Security:

  - `OAuth2.0` (unknown)
    oauth2

## Header parameters:

  - `X-ApiVersion` (integer, required)

## Request body:

  - `application/json-patch+json, application/json, text/json, application/*+json` (unknown)
    The query request.

## Request fields (application/json-patch+json):

  - `query` (object)

  - `query.filter` (object)
    Represents a filter used in a query. The `type` property determines the filter type and its required properties. See `FilterType` for available types and examples below.

  - `query.filter.type` (string, required)
    Specifies the type of filter to apply in a query. Each filter type has specific required properties:
- **Composite**: Combines multiple filters with a logical operator. Requires `operator` (AND, OR) and `children` array.
- **Not**: Negates a child filter. Requires `child` filter object.
- **Property**: Filters by property value. Requires `property`, `operator`, `value`, and `data_type`. Valid `data_type` values: `String`, `Int`, `Long`, `Decimal`, `Float`, `DateTime`, `DateTimeOffset`, `Bool`. Optional: `culture`.
- **Relation**: Filters by relation. Requires `relation` name. Does not support operators. Optional: `parent_id` or `child_id`.
- **CreatedBy**: Filters by creator. Requires `user_id`.
- **ModifiedBy**: Filters by modifier. Requires `user_id`.
- **SecuredAncestors**: Filters by secured ancestor. Requires `ancestor_id`.
- **Id**: Filters by entity ID. Requires `operator` and `value`.
- **Identifier**: Filters by entity identifier. Requires `operator` and `value`.
- **Definition**: Filters by entity definition. Requires `operator` and `name`.
- **Modules**: Filters by module membership. Requires `modules` array.
- **CreatedOn**: Filters by creation date. Requires `operator` and `value` (ISO 8601 format).
- **ModifiedOn**: Filters by modification date. Requires `operator` and `value` (ISO 8601 format).
    Enum: "Composite", "Not", "Property", "Relation", "CreatedBy", "ModifiedBy", "SecuredAncestors", "Id", "Identifier", "Definition", "Modules", "CreatedOn", "ModifiedOn"

  - `query.skip` (integer)

  - `query.take` (integer)

  - `query.sorting` (array)

  - `query.sorting.field_type` (string)
    Enum: "Property", "System"

  - `query.sorting.field` (string, required)

  - `query.sorting.culture` (string)

  - `query.sorting.order` (string, required)
    Enum: "Desc", "Asc"

  - `query.scroll_time` (string)

  - `load_configuration` (object)
    Represents the configuration for loading an entity.

  - `load_configuration.culture_option` (object)
    Represents options for loading cultures.

  - `load_configuration.culture_option.load_option` (string)
    An enum of possible load options.
    Enum: "None", "Default", "Custom", "All"

  - `load_configuration.culture_option.cultures` (array)
    Gets or sets a list of culture names that need to be loaded. This is only useful when `Stylelabs.M.Base.Entities.Loading.CultureLoadOption.LoadOption` is `Stylelabs.M.Base.Entities.Loading.LoadOption.Custom`.

  - `load_configuration.property_option` (object)
    Represents options for loading properties.

  - `load_configuration.property_option.properties` (array)
    Gets or sets a list of property names (case insensitive) that need to be loaded.
This is only useful when `Stylelabs.M.Base.Entities.Loading.PropertyLoadOption.LoadOption` is `Stylelabs.M.Base.Entities.Loading.LoadOption.Custom`.

  - `load_configuration.relation_option` (object)
    Represents options for loading relations.

  - `load_configuration.relation_option.relations` (array)
    Gets or sets a list of relations that need to be loaded.
This is only useful when `Stylelabs.M.Base.Entities.Loading.RelationLoadOption.LoadOption` is `Stylelabs.M.Base.Entities.Loading.LoadOption.Custom`.

  - `load_configuration.relation_option.relations.name` (string)
    Name of the relation (case insensitive).

  - `load_configuration.relation_option.relations.role` (string)
    Enum: "Parent", "Child"

  - `load_configuration.relation_option.max_related_items` (integer)
    Gets or sets the maximum number of related items for each relation.

## Response 200:

  - `200` (unknown)
    Successful operation

## Response 200 fields (application/json):

  - `scroll_id` (string)

  - `items` (array)
    Gets or sets the list of items.

  - `items.link` (object)
    Represents a link to a resource.

  - `items.link.href` (string)
    Gets or sets the URI that points to the resource this link refers to.

  - `items.link.filename_properties` (array)
    Gets or sets the URI that points to the resource this link refers to.

  - `items.link.title` (string)
    Gets or sets the title that describes this link.

  - `items.link.templated` (boolean)
    Gets or sets a value indicating whether the contained URI is a template.

  - `items.entity` (object)
    Represents an entity resource with various properties, relations, and metadata.

  - `items.entity.id` (integer)
    The ID for the entity, for example, `39752`.

  - `items.entity.identifier` (string)
    The identifier for the entity.

  - `items.entity.cultures` (array)
    The cultures associated with the entity, for example, `en-US`.

  - `items.entity.properties` (object)
    The properties of the entity.

  - `items.entity.relations` (object)
    The relations of the entity.

  - `items.entity.created_on` (string)
    The date and time when the entity was created.

  - `items.entity.modified_on` (string)
    The date and time when the entity was last modified.

  - `items.entity.locked_on` (string)
    The date and time when the entity was locked.

  - `items.entity.requested_permissions` (object)
    The requested permissions with identification if a certain user has the permissions.

  - `items.entity.is_root_taxonomy_item` (boolean)
    Gets or sets a value indicating whether the entity is a root taxonomy item.

  - `items.entity.is_path_root` (boolean)
    Gets or sets a value indicating whether the entity is a path root.

  - `items.entity.inherits_security` (boolean)
    Gets or sets a value indicating whether the entity inherits security.

  - `items.entity.is_system_owned` (boolean)
    Gets or sets a value indicating whether the entity is system owned.

  - `items.entity.version` (integer)
    The version of the entity.

  - `items.entity.modules` (array)
    The modules associated with the entity.

  - `total_items` (integer)
    Gets or sets the total number of items.

  - `returned_items` (integer)
    Gets or sets the number of returned items.

  - `offset` (integer)
    Gets or sets the offset of the items.

## Response 400:

  - `400` (unknown)
    Request is not valid

## Response 401:

  - `401` (unknown)
    Unauthorized request or invalid access token