Search and saved views

The API provides very flexible search possibilities. You can filter almost anything by any field, even relational, specify arrays of possible values, and use operators like greater than or lesser than. The search logic is not hardcoded and can be used on almost any endpoint. Furthermore, you can save any search as a "saved view", then load it again.

Search endpoint

Post a JSON body to entity/search, for example POST api/v1/products/search
You will get the same response format as on the regular GET endpoint, furthermore, all the GET parameters will work on search as well (such as expanding relations, page size, page number, sorting, etc).
For request body syntax, refer to the section below.
For field names, refer to the Search field column on GET endpoint reference pages. These names may not always match those on GET endpoints, as search works directly with the database.

Request body syntax

"field": "value" - find items where field contains value
"field": ["value1","value2"] - find items where field contains either value1 or value2
"field": [1,2] - find items where field is 1 or 2
"relation": {"field": "value"} - search relational data
"field": {"operator": ">", "value": 1} - search using operators (see below)

Available operators:
['=', '<', '>', '<=', '>=', '!=', 'contains', 'notcontains']

You can combine the above syntax, for example search with operators inside relations, etc.

Search examples

JSON

// entity with title containing "abc" and with collection 1
{
    "title": "abc",
    "collections": [1] // this is a shortcut for "collections": [{”id”:1}]
}


// bad example
{
    "collection_id": 1, // this will NOT work because there is no such field in products, use "collections": [1]
    "type_id": 1, // this will work but "types": [1] is recommended for consistency
}


// entity with title containing "abc" or with collection 1
[{
    "title": "abc"
}, {
    "collections": [1]
}]


// entity with title containing "abc" or "asd" OR with collection 1
[{
    "title": ["abc", "asd"]
}, {
    "collections": [1]
}]

// entity with id 1,2,3
{
    "id": [1, 2, 3]
}

// entity with id 1,2,3 and price more than 20
{
    "id": [1, 2, 3],
    "price": {
        "operator": ">",
        "value": 20
    }
}


// Products with title containing "abc"
// that belong collections containing "shirts"
{
    "title": "abc",
    "collections": {
        "title": "shirts"
    }
}

// Products with title containing "abc"
// that belong collection with title = "shirts" OR any not manual collections
{
    "title": "abc",
    "collections": [{
        "title": {
            "operator": "=",
            "value": "shirts"
        }
    }, {
        "auto_add": 0
    }]
}


// Timestamp
{
  // exact matching
  "created_at": "<timeStamp>"
}

{
  // time range
  // if we want to fetch yesterday, timestamp will be 01.01.2016 00:00:00 – 01.01.2016 23:59:59
  "created_at": {
    "start": "<timeStamp>",
    "end": "<timeStamp>"
  }
}

Saved views

If you wish to save a search query, send the same request body to entity/savedviews, as in:

JSON

POST api/v1/products/savedviews

{
  "id": 1,
  "type": "products",
  "json": "{\"title\":\"abc\",\"collections\":{\"auto_add\":0}}"
}

To load it back:

JSON

GET api/v1/products/savedviews

{
  "id": 1,
  "type": "products",
  "json": "{\"title\":\"abc\",\"collections\":{\"auto_add\":0}}"
}

Then you may use the same JSON that you got back in regular search to fetch the results.
Keep in mind that these views will be available in the Refine View window in whichever feature of the app this belongs to, for example Products.

To delete a saved view:
DELETE api/v1/products/savedviews/ID