Overview

List endpoints accept a search query parameter that filters results by attribute values. The same shape works for /products, /variants, and /skus.

Shape

search is a URL-encoded JSON object. Each key names an attribute, and the value is an array of operator + value pairs. Multiple entries on the same key apply together (e.g. a price range as two entries).

{
  "product.description": [
    { "operator": "CONTAINS", "value": "organic" }
  ],
  "product.price": [
    { "operator": "GREATER_THAN", "value": 100 },
    { "operator": "LESS_THAN", "value": 500 }
  ]
}

Keys

A key is <entity>.<attribute> where:

• entity is one of product, variant, sku. It selects which entity level the attribute lives on.
• attribute is the attribute's key as defined in your workspace.

Keys starting with _ are system filters that target built-in fields rather than configured attributes. See System filters.

Combining filters

By default all filters must match (AND logic). Pass search_mode=any to switch to OR logic across the top-level keys.

curl "https://api.emfas.ai/v1/products?search=$(jq -rRn --arg j '{
  "product.description": [{"operator": "CONTAINS", "value": "organic"}]
}' '$j' | jq -sRr @uri)&search_mode=all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Operators

The operators that are valid for a filter depend on the attribute's type. A CONTAINS operator works on text attributes but not on numeric ones, and GREATER_THAN is the opposite. See Operators for the full matrix and per-operator value shape.

Error responses

If a filter is malformed — unknown key, invalid operator for the attribute's type, value shape that does not match the operator — the endpoint returns 400 Bad Request with an error field describing what failed.

{ "error": "filter 'product.price': operator 'CONTAINS' is not valid for numeric fields" }