ItemsSearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/catalogapi-com/json-schema/catalogapi-com-items-search-request-schema.json",
  "title": "ItemsSearchRequest",
  "description": "Request body for POST /items/search endpoint.\n\nUse this endpoint for complex filtering with the Filter DSL. The `filter` field is optional\nand accepts nested boolean logic. All fields are optional and work alongside the filter.\n\n## Request Body Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `filter` | object | No | Filter DSL object for complex queries (see Filter schema) |\n| `search` | string | No | Full-text search query for item names and descriptions |\n| `brand` | string | No | Filter by brand name (exact match) |\n| `is_primary` | boolean | No | When true, returns only primary items |\n| `page` | integer | No | Page number for pagination (default: 1) |\n| `per_page` | integer | No | Results per page, 1-100 (default: 25) |\n| `sort` | string | No | Sort order (default: \"rank asc\") |\n| `brand_faceting` | string | No | Include brand facets: \"top\" or \"full\" |\n| `tag_faceting` | string | No | Include tag facets: \"top\" or \"full\" |\n\n## Sort Options\n- `rank asc` / `rank desc` - Sort by relevance rank\n- `price asc` / `price desc` - Sort by price\n- `points asc` / `points desc` - Sort by points\n- `name asc` / `name desc` - Sort alphabetically by name\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/catalogapi-com-openapi.yml#/components/schemas/ItemsSearchRequest",
  "properties": {
    "brand": {
      "description": "Filter by brand name (exact match). Use this for brand name search; use filter.eq.brand_id for ID-based filtering.",
      "type": "string"
    },
    "brand_faceting": {
      "description": "Include brand facets in response. 'top' returns top brands, 'full' returns all brands with counts.",
      "enum": [
        "top",
        "full"
      ],
      "type": "string"
    },
    "filter": {
      "$ref": "#/$defs/Filter"
    },
    "is_primary": {
      "description": "When true, returns only primary items (excludes variant items). Default: returns all items.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Page number for pagination. First page is 1.",
      "minimum": 1,
      "type": "integer"
    },
    "per_page": {
      "default": 25,
      "description": "Number of items per page. Minimum: 1, Maximum: 100, Default: 25.",
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "search": {
      "description": "Full-text search query. Searches item names and descriptions. Combined with filter using AND logic.",
      "type": "string"
    },
    "sort": {
      "default": "rank asc",
      "description": "Sort order for results. Format: 'field direction' where direction is 'asc' or 'desc'.",
      "enum": [
        "rank asc",
        "rank desc",
        "price asc",
        "price desc",
        "points asc",
        "points desc",
        "name asc",
        "name desc"
      ],
      "type": "string"
    },
    "tag_faceting": {
      "description": "Include tag facets in response. 'top' returns top tags, 'full' returns all tags with counts.",
      "enum": [
        "top",
        "full"
      ],
      "type": "string"
    }
  },
  "type": "object",
  "$defs": {
    "Filter": {
      "description": "A Filter DSL object for complex boolean queries.\n\n## Comparison Operators\n- `eq`: Equal to a single value - `{\"eq\": {\"brand_id\": 5984}}`\n- `ne`: Not equal to a single value - `{\"ne\": {\"item_type_id\": 200}}`\n- `in`: Matches any value in a list - `{\"in\": {\"brand_id\": [5984, 114, 225]}}`\n- `not_in`: Excludes all values in a list - `{\"not_in\": {\"item_type_id\": [200, 100]}}`\n- `gt`: Greater than (numeric fields only) - `{\"gt\": {\"price\": 100}}`\n- `gte`: Greater than or equal (numeric fields only) - `{\"gte\": {\"points\": 1000}}`\n- `lt`: Less than (numeric fields only) - `{\"lt\": {\"price\": 500}}`\n- `lte`: Less than or equal (numeric fields only) - `{\"lte\": {\"points\": 5000}}`\n- `between`: Between two values inclusive (numeric fields only) - `{\"between\": {\"price\": [50, 200]}}`\n\n## Boolean Operators\n- `and`: All conditions must match (requires 2+ conditions)\n- `or`: Any condition must match (requires 2+ conditions)\n\n## Allowed Filter Fields\n| Field | Type | Description |\n|-------|------|-------------|\n| `brand_id` | integer | Filter by brand ID |\n| `category_id` | integer | Filter by category ID |\n| `tag_id` | integer | Filter by tag ID |\n| `item_type_id` | integer | Filter by item type ID (200 = gift cards) |\n| `catalog_item_id` | integer | Filter by specific catalog item ID |\n| `fulfillment_type` | string | Filter by fulfillment type (\"physical\" or \"digital\") |\n| `price` | number | Filter by price (supports gt, gte, lt, lte, between) |\n| `points` | integer | Filter by points (supports gt, gte, lt, lte, between) |\n\n## Limits\n- Maximum nesting depth: 5 levels\n- Maximum total clauses: 50\n- Maximum values in `in`/`not_in`: 500\n\n## Examples\n\nSimple equality:\n```json\n{\"eq\": {\"brand_id\": 5984}}\n```\n\nMultiple values:\n```json\n{\"in\": {\"brand_id\": [5984, 114, 225]}}\n```\n\nPrice range:\n```json\n{\"between\": {\"price\": [50, 200]}}\n```\n\nComplex nested query (physical items that are gift cards OR priced $50-$200):\n```json\n{\n  \"and\": [\n    {\"eq\": {\"fulfillment_type\": \"physical\"}},\n    {\"or\": [\n      {\"eq\": {\"item_type_id\": 200}},\n      {\"between\": {\"price\": [50, 200]}}\n    ]}\n  ]\n}\n```\n",
      "oneOf": [
        {
          "description": "Logical AND - all conditions must match. Requires at least 2 conditions. Can be nested up to 5 levels deep.",
          "properties": {
            "and": {
              "description": "Array of filter conditions (all must match)",
              "items": {
                "$ref": "#/$defs/Filter"
              },
              "minItems": 2,
              "type": "array"
            }
          },
          "required": [
            "and"
          ],
          "title": "AndOperator",
          "type": "object"
        },
        {
          "description": "Logical OR - any condition must match. Requires at least 2 conditions. Can be nested up to 5 levels deep.",
          "properties": {
            "or": {
              "description": "Array of filter conditions (any must match)",
              "items": {
                "$ref": "#/$defs/Filter"
              },
              "minItems": 2,
              "type": "array"
            }
          },
          "required": [
            "or"
          ],
          "title": "OrOperator",
          "type": "object"
        },
        {
          "description": "Equal to comparison. Specify one field and its value.",
          "properties": {
            "eq": {
              "description": "Specify exactly one field with its value",
              "properties": {
                "brand_id": {
                  "description": "Filter by brand ID",
                  "type": "integer"
                },
                "catalog_item_id": {
                  "description": "Filter by catalog item ID",
                  "type": "integer"
                },
                "category_id": {
                  "description": "Filter by category ID",
                  "type": "integer"
                },
                "fulfillment_type": {
                  "description": "Filter by fulfillment type",
                  "enum": [
                    "physical",
                    "digital"
                  ],
                  "type": "string"
                },
                "item_type_id": {
                  "description": "Filter by item type ID (200 = gift cards)",
                  "type": "integer"
                },
                "points": {
                  "description": "Filter by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Filter by price",
                  "type": "number"
                },
                "tag_id": {
                  "description": "Filter by tag ID",
                  "type": "integer"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "eq"
          ],
          "title": "EqOperator",
          "type": "object"
        },
        {
          "description": "Not equal to comparison. Specify one field and its value.",
          "properties": {
            "ne": {
              "description": "Specify exactly one field with its value",
              "properties": {
                "brand_id": {
                  "description": "Filter by brand ID",
                  "type": "integer"
                },
                "catalog_item_id": {
                  "description": "Filter by catalog item ID",
                  "type": "integer"
                },
                "category_id": {
                  "description": "Filter by category ID",
                  "type": "integer"
                },
                "fulfillment_type": {
                  "description": "Filter by fulfillment type",
                  "enum": [
                    "physical",
                    "digital"
                  ],
                  "type": "string"
                },
                "item_type_id": {
                  "description": "Filter by item type ID (200 = gift cards)",
                  "type": "integer"
                },
                "points": {
                  "description": "Filter by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Filter by price",
                  "type": "number"
                },
                "tag_id": {
                  "description": "Filter by tag ID",
                  "type": "integer"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "ne"
          ],
          "title": "NeOperator",
          "type": "object"
        },
        {
          "description": "Greater than comparison. Numeric fields only.",
          "properties": {
            "gt": {
              "description": "Specify exactly one numeric field with its value",
              "properties": {
                "points": {
                  "description": "Compare by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Compare by price",
                  "type": "number"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "gt"
          ],
          "title": "GtOperator",
          "type": "object"
        },
        {
          "description": "Greater than or equal comparison. Numeric fields only.",
          "properties": {
            "gte": {
              "description": "Specify exactly one numeric field with its value",
              "properties": {
                "points": {
                  "description": "Compare by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Compare by price",
                  "type": "number"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "gte"
          ],
          "title": "GteOperator",
          "type": "object"
        },
        {
          "description": "Less than comparison. Numeric fields only.",
          "properties": {
            "lt": {
              "description": "Specify exactly one numeric field with its value",
              "properties": {
                "points": {
                  "description": "Compare by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Compare by price",
                  "type": "number"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "lt"
          ],
          "title": "LtOperator",
          "type": "object"
        },
        {
          "description": "Less than or equal comparison. Numeric fields only.",
          "properties": {
            "lte": {
              "description": "Specify exactly one numeric field with its value",
              "properties": {
                "points": {
                  "description": "Compare by points",
                  "type": "integer"
                },
                "price": {
                  "description": "Compare by price",
                  "type": "number"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "lte"
          ],
          "title": "LteOperator",
          "type": "object"
        },
        {
          "description": "Matches any value in the list. Specify one field with an array of values.",
          "properties": {
            "in": {
              "description": "Specify exactly one field with an array of values",
              "properties": {
                "brand_id": {
                  "description": "Filter by brand IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "catalog_item_id": {
                  "description": "Filter by catalog item IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "category_id": {
                  "description": "Filter by category IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "fulfillment_type": {
                  "description": "Filter by fulfillment types",
                  "items": {
                    "enum": [
                      "physical",
                      "digital"
                    ],
                    "type": "string"
                  },
                  "type": "array"
                },
                "item_type_id": {
                  "description": "Filter by item type IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "points": {
                  "description": "Filter by points",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "price": {
                  "description": "Filter by prices",
                  "items": {
                    "type": "number"
                  },
                  "type": "array"
                },
                "tag_id": {
                  "description": "Filter by tag IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "in"
          ],
          "title": "InOperator",
          "type": "object"
        },
        {
          "description": "Excludes all values in the list. Specify one field with an array of values.",
          "properties": {
            "not_in": {
              "description": "Specify exactly one field with an array of values",
              "properties": {
                "brand_id": {
                  "description": "Filter by brand IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "catalog_item_id": {
                  "description": "Filter by catalog item IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "category_id": {
                  "description": "Filter by category IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "fulfillment_type": {
                  "description": "Filter by fulfillment types",
                  "items": {
                    "enum": [
                      "physical",
                      "digital"
                    ],
                    "type": "string"
                  },
                  "type": "array"
                },
                "item_type_id": {
                  "description": "Filter by item type IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "points": {
                  "description": "Filter by points",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "price": {
                  "description": "Filter by prices",
                  "items": {
                    "type": "number"
                  },
                  "type": "array"
                },
                "tag_id": {
                  "description": "Filter by tag IDs",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "not_in"
          ],
          "title": "NotInOperator",
          "type": "object"
        },
        {
          "description": "Between comparison (inclusive). Specify one numeric field with [min, max] range.",
          "properties": {
            "between": {
              "description": "Specify exactly one numeric field with [min, max] range",
              "properties": {
                "points": {
                  "description": "Points range as [min, max]",
                  "items": {
                    "type": "integer"
                  },
                  "maxItems": 2,
                  "minItems": 2,
                  "type": "array"
                },
                "price": {
                  "description": "Price range as [min, max]",
                  "items": {
                    "type": "number"
                  },
                  "maxItems": 2,
                  "minItems": 2,
                  "type": "array"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "between"
          ],
          "title": "BetweenOperator",
          "type": "object"
        }
      ],
      "title": "Filter",
      "type": "object"
    }
  }
}