Sitecore API catalog/Querying API/Querying

Querying

The Querying API is responsible for fetching multiple pages of results sequentially.

The Querying API supports the following operators:

  • Equals
  • NotEquals
  • Gt
  • Lt
  • Gte
  • Lte
  • Contains
  • StartsWith
  • EndsWith
Operations

Retrieve entities using a query string

Request

Lists entities that match the query in a request body.

Note
The Querying API supports various operators for filter types that use an operator field. Relation filters do not support operators.
The query filter supports multiple types, each with specific properties.
Note
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.

  • 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"}
Security
OAuth2.0
Headers
X-ApiVersionintegerrequired

API version. Must be set to 3.

Example:3
Body

The query request.

queryobject(Query)
Example:
{
  "filter": {
    "type": "Composite",
    "operator": "AND",
    "children": [ … ]
  },
  "skip": 0,
  "take": 1,
  "sorting": [
    { … }
  ]
}
load_configurationobject(EntityLoadConfiguration)

Represents the configuration for loading an entity.

Example:
{
  "load_entities": true,
  "property_option": {
    "load_option": "None",
    "properties": []
  },
  "relation_option": {
    "load_option": "Custom",
    "relations": [ … ]
  },
  "culture_option": {
    "load_option": "All",
    "cultures": []
  }
}
curl -i -X POST \
  https://your-server/api/entities/query \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'X-ApiVersion: 3' \
  -d '{
    "query": {
      "filter": {
        "type": "Composite",
        "operator": "AND",
        "children": [
          {
            "type": "Definition",
            "operator": "Equals",
            "name": "M.Asset"
          },
          {
            "type": "Relation",
            "relation": "FinalLifeCycleStatusToAsset",
            "parent_id": 543
          }
        ]
      },
      "skip": 0,
      "take": 1,
      "sorting": [
        {
          "field_type": "Property",
          "field": "created_on",
          "culture": "en-us",
          "order": "Desc"
        }
      ]
    },
    "load_configuration": {
      "load_entities": true,
      "property_option": {
        "load_option": "None",
        "properties": []
      },
      "relation_option": {
        "load_option": "Custom",
        "relations": [
          {
            "name": "AssetToAssociatedCollections"
          }
        ]
      },
      "culture_option": {
        "load_option": "All",
        "cultures": []
      }
    }
  }'

Responses

Successful operation

Bodyapplication/json
scroll_idstring or null
itemsArray of objects or null(SearchDocumentResource)

Gets or sets the list of items.

total_itemsinteger or null, (int64)

Gets or sets the total number of items.

returned_itemsinteger or null, (int64)

Gets or sets the number of returned items.

offsetinteger or null, (int32)

Gets or sets the offset of the items.

nextobject(Link)

Represents a link to a resource.

previousobject(Link)

Represents a link to a resource.

Response
{
  "scroll_id": "string",
  "items": [
    { … }
  ],
  "total_items": 0,
  "returned_items": 0,
  "offset": 0,
  "next": {
    "href": "string",
    "filename_properties": [ … ],
    "title": "string",
    "templated": false
  },
  "previous": {
    "href": "string",
    "filename_properties": [ … ],
    "title": "string",
    "templated": false
  }
}