> ## Documentation Index > Fetch the complete documentation index at: https://docs.glood.ai/llms.txt > Use this file to discover all available pages before exploring further. # Filters > DB-driven facet (filter) definitions for the resolved filter tree. No live counts (see filter-aggregations). Auth: `Authorization: Bearer ` + `x-shop`. ```json 200 theme={null} { "facets": [ { "id": 1, "key": "color", "title": "Color", "type": "color", "attribute_type": "option", "position": 1, "expanded": true, "visible": true, "operator": "or", "settings": { "multi_select": true, "show_count": true, "collapsible": true, "searchable": false, "show_more": true, "max_display": 10 }, "min": null, "max": null, "step": null, "unit": null, "suffix": null, "values": [ { "value": "red", "label": "Red", "count": null, "position": 1, "hex": "#ff0000", "image": null, "order": null } ] }, { "id": 2, "key": "price", "title": "Price", "type": "number", "attribute_type": "price", "position": 2, "expanded": true, "visible": true, "operator": "or", "settings": { "multi_select": false, "show_count": true, "collapsible": true, "searchable": false, "show_more": false, "max_display": 10 }, "min": 0, "max": 1000, "step": 1, "unit": "$", "suffix": "", "values": [] } ], "tree": { "id": 5, "target_page": "search", "target_ids": [10], "is_default": false, "title": "Search filters", "settings": {} }, "metadata": { "locale": "en-US", "market": null, "region": "toronto", "total_facets": 2 } } ``` ```json 200 - no tree configured theme={null} { "facets": [], "tree": { "id": null, "target_page": "search", "target_ids": [], "is_default": true, "title": "Filters", "settings": {} }, "metadata": { "locale": "en-US", "market": null, "region": "toronto", "total_facets": 0 } } ``` ```json 400 theme={null} { "error": [ { "message": "\"tree\" must be a number", "path": ["tree"], "type": "number.base", "context": { "label": "tree", "key": "tree" } } ], "ok": false } ``` ## OpenAPI ````yaml POST /api/storefront/v1/headless/filters openapi: 3.0.1 info: title: Glood.AI API Reference description: Glood.AI API Reference license: name: MIT version: 1.0.0 servers: - url: https://storefront.glood.ai security: - bearerAuth: [] paths: /api/storefront/v1/headless/filters: servers: - url: https://search.glood.ai post: description: >- DB-driven facet (filter) definitions for the resolved filter tree. No live counts (see filter-aggregations). Auth: `Authorization: Bearer ` + `x-shop`. parameters: - name: x-shop in: header description: >- Shopify store URL. Resolves the shop for the request (headless does not accept `?shop=`). required: true schema: type: string example: shop.myshopify.com requestBody: description: Request body content: application/json: schema: $ref: '#/components/schemas/HeadlessFiltersRequest' responses: '200': description: Filter definitions content: application/json: schema: $ref: '#/components/schemas/HeadlessFiltersResponse' '400': description: Validation or shop error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: HeadlessFiltersRequest: type: object description: Filter definitions request (DB-driven, no live counts). properties: collection: oneOf: - type: string - type: integer description: >- Collection id to resolve a collection-scoped tree. String or integer. tree: type: integer description: Explicit filter tree id (overrides target-page resolution). target_page: type: string description: Page whose tree to resolve. enum: - search - collection target_id: type: integer description: Target object id (e.g. collection id). locale: type: string description: BCP-47 locale. default: en-US market: type: integer description: Shopify market id. include_values: type: boolean description: Include each facet's selectable values. default: true include_disabled: type: boolean description: Include disabled filters. default: false visitor_id: type: string description: >- Anonymous device/browser UID (the `gl_s_uid` cookie). The primary personalization key; stays stable when a customer logs in. client_id: type: string description: Per-session / per-device identifier. customer_id: type: string description: >- Shopify customer id. Present only when the shopper is logged in; enables customer-level personalization. HeadlessFiltersResponse: type: object description: DB-driven facet definitions for the resolved tree. properties: facets: type: array description: Facet definitions, sorted by position. items: $ref: '#/components/schemas/HeadlessSearchFacet' tree: nullable: true allOf: - type: object description: Resolved filter tree (metadata only). properties: id: type: integer nullable: true description: Tree id (null in the empty-fallback tree). target_page: type: string description: Page the tree targets. enum: - search - collection target_ids: type: array description: Object ids the tree applies to. items: type: integer is_default: type: boolean description: Whether this is the default tree. title: type: string description: Localised tree title. settings: type: object description: Tree-level settings. description: Resolved tree, or the empty-fallback tree when none is configured. metadata: type: object description: Response metadata. properties: locale: type: string description: Resolved locale. market: type: integer nullable: true description: Echoed market id. region: type: string description: Data-plane region. example: toronto total_facets: type: integer description: Number of facets returned. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string HeadlessSearchFacet: type: object description: A DB-driven facet (filter) definition, without live counts. properties: id: type: integer description: Filter definition id. key: type: string description: Stable filter key used when applying the filter (e.g. `color`). title: type: string description: Localised display title of the facet. type: type: string description: Data type of the facet (e.g. `list`, `number`, `color`, `size`). attribute_type: type: string description: >- Underlying product attribute the facet maps to (e.g. `option`, `price`, `tag`, `vendor`). position: type: integer description: Display order of the facet within its tree. expanded: type: boolean description: Whether the facet renders expanded by default. visible: type: boolean description: Whether the facet is shown in the UI. operator: type: string description: Default combine operator for selected values. enum: - or - and settings: type: object description: Facet presentation settings (functional only, no CSS/JS). properties: multi_select: type: boolean description: Allow selecting multiple values. show_count: type: boolean description: Show per-value match counts. collapsible: type: boolean description: Facet can be collapsed. searchable: type: boolean description: Show a value search box within the facet. show_more: type: boolean description: Show a 'show more' toggle when values exceed `max_display`. max_display: type: integer description: How many values to show before the 'show more' toggle. min: type: number nullable: true description: Range minimum. Populated only for numeric / price facets. max: type: number nullable: true description: Range maximum. Populated only for numeric / price facets. step: type: number nullable: true description: Slider step. Numeric / price facets only. unit: type: string nullable: true description: Value prefix (e.g. currency symbol). Numeric / price facets only. suffix: type: string nullable: true description: Value suffix (e.g. unit label). Numeric / price facets only. values: type: array description: >- Selectable values for this facet. Empty when `include_values` is false. items: $ref: '#/components/schemas/HeadlessSearchFacetValue' HeadlessSearchFacetValue: type: object description: A selectable value within a facet definition. properties: value: type: string description: Raw facet value used when applying the filter. label: type: string description: Human-readable label for the value. count: type: integer nullable: true description: >- Live match count. Always `null` in facet definitions (API 3); populated by filter aggregations (API 4). position: type: integer description: Display order of this value within the facet. hex: type: string nullable: true description: Swatch color hex, for `color` facets only. image: type: string nullable: true description: Swatch image URL, for `color` facets only. order: type: integer nullable: true description: Explicit sort order, for `size` facets only. securitySchemes: bearerAuth: type: http scheme: bearer ````