Test Enterprise-Class Web CMS Scrivito Free for 30 Days
Test Scrivito Free for 30 Days

Search objects

Searches for objects using a powerful query language.

PUT /tenants/:tenant_id/workspaces/:working_copy_id/objs/search
PUT /tenants/:tenant_id/workspaces/published/objs/search

Params

  • tenant_id – The ID of the tenant.
  • working_copy_id – The ID of the working copy to search in.

Params as part of the payload

  • boost – The list of boost queries.
  • continuation – A continuation handle as returned by a previous search request.
  • facets – A list of facet requests.
  • include_objs – Specifies whether to include the objects in the result or to return only their IDs.
  • options – A map of additional options. The supported keys are include_deleted, include_editing_assets, and site_aware. To query any other site than the default one (with multi-site tenants), set site_aware to true and specify the _site_id in your query.
  • order_by – A list of sort criteria to be applied to the search result.
  • query – The list of search queries. Each element restricts the result using “and”. To negate an additional query, specify the negate: true parameter. The field value may be * which acts as a wildcard for having all attributes searched.
  • size – The maximum number of hits to return.

Example of the boost parameter:

[
  {
    "condition": [
      {
        "field": "_obj_class",
        "operator": "equals",
        "value": "Product"
      }
    ],
    "factor": 10.0
  }
]

Example of the facets parameter:

[
  {
    "attribute": "title",
    "limit": 3,           // default: 10
    "include_objs": 5     // default: 0
  },
  {
    "attribute": "type"
  }
]

Example of the options parameter:

{
  "include_deleted": true,
  "include_editing_assets": true,
  "site_aware": true
}

Example of the order_by parameter:

[
  ["_last_changed", "desc"],
  ["author", "asc"]
]

Example of the query parameter:

[
  {
    "field": "language",
    "operator": "equals",
    "value": ["en", "fr"]
  },
  {
    "field": "title",
    "operator": "equals",
    "value": "Foo"
  }
]

Response

A map containing the following keys:

  • continuation – A continuation handle; present if not all hits were returned. In this case, add the continuation key and value to the subsequent request to fetch the next batch.
  • facets – A list of facet results; present if facets were requested.
  • objs – A list of found objects; present if include_objs was set.
  • results – A list of maps containing the found object IDs.

The results are restricted to the visibility categories applicable to the user.

Examples

Find CMS objects whose title or description attribute value starts with term:

curl \
  -X PUT \
  -H 'Content-Type: application/json' \
  -u 'api_token:MYTOKEN' \
  -d '{
    "query": [
      {
        "field": ["title", "description"],
        "operator": "contains_prefix",
        "value": "term"
      }
    ]
  }' \
  https://api.scrivito.com/tenants/:tenant_id/workspaces/published/objs/search

Same as above, but only find CMS objects not in the /products path (whose _path attribute value does not start with /products):

curl \
  -X PUT \
  -H 'Content-Type: application/json' \
  -u 'api_token:MYTOKEN' \
  -d '{
    "query": [
      {
        "field": ["title", "description"],
        "operator": "contains_prefix",
        "value": "term"
      },
      {
        "field": "_path",
        "operator": "starts_with",
        "value": "/products",
        "negate": true
      }
    ]
  }' \
  https://api.scrivito.com/tenants/:tenant_id/workspaces/published/objs/search
{
  "total": 109,
  "results": [
    {"id": "0028b1560997eb97"},
    {"id": "0036cdd0d32969d2"},
    {"id": "00eff53b042422ea"},
    {"id": "0137a38b837bd47d"},
    {"id": "01d4110c101e0490"},
    {"id": "02c04916ee8157d2"},
    {"id": "02dc4285745e08e7"},
    {"id": "03348c34aa95843d"},
    {"id": "034617d259ad31af"},
    {"id": "03727495ecbcdb6d"}
  ],
  "continuation": "[1,10,0]"
}

Error codes

  • validation.illegal_value
  • validation.invalid_value

Remarks

  • The GET method is supported as well.
  • The result never includes more than 100 hits, even if size is set to a larger value.
  • The number of facet queries is limited to 10.
  • The number of returned objects may be less than the number of returned object IDs if the tenant’s rate limit was reached.