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

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
  }
}