> ## Documentation Index > Fetch the complete documentation index at: https://docs.doofinder.com/llms.txt > Use this file to discover all available pages before exploring further. # Get category page results > Returns search results for the category page whose URL pattern matches the provided `url`. The `url` is matched against the URL patterns configured for the given search engine. The highest-priority matching pattern determines the base filter and facets applied to the search. Client-supplied `filter` params are merged on top: keys that overlap with the pattern filter are ignored, the rest are added to the query. **Sort order:** If `sort` params are provided they take precedence. Otherwise, the sort configured in the category page settings is applied. If neither is configured, results are returned in the engine's default order. ## OpenAPI ````yaml /openapi/category-merchandising-v1.yaml get /category_merchandising/{hashid} openapi: 3.0.0 info: title: Category Merchandising API version: '1.0' x-logo: url: https://admin.doofinder.com/images/logo.svg backgroundColor: '#33268C' altText: Doofinder API Reference description: > The Category Merchandising API returns search results for a category page. Requests are made to `https://{zone}-category-merchandising.doofinder.com/api/1` — for example, `https://eu1-category-merchandising.doofinder.com/api/1` for the EU region. It matches the request URL against URL patterns configured in your search engine and applies the corresponding filter, returning a paginated result set suitable for rendering a category listing page. You can manage your category pages and URL patterns in the [Doofinder admin panel](https://admin.doofinder.com) under **Category Merchandising → Configuration**. # Authentication The API supports two authentication methods: ## CORS (browser requests) When a request originates from a domain registered as an allowed origin for the search engine, the API authenticates it automatically via CORS — no `Authorization` header is required. Allowed origins are derived from the site URL configured in your search engine settings in the [Doofinder admin panel](https://admin.doofinder.com). ## API Token (server-side requests) For requests that do not come from an allowed origin, include an `Authorization` header with a valid API token: ``` Authorization: Token {your_token} ``` The token is validated against the account that owns the search engine identified by `hashid`. Requests with a missing token, an invalid token, or a token that does not have access to the requested search engine receive a **401 Unauthorized** response. # URL matching Each search engine has a set of URL patterns. When you call the endpoint, the API evaluates the provided `url` against all active patterns (ordered by priority, lowest wins). The first matching pattern determines the base filter applied to the search. If no pattern matches, or if the category page is inactive, the API returns **404 Not Found**. # Filtering The base filter is always derived from the matched URL pattern and cannot be overridden by the caller. You may pass additional `filter[field][]=value` query parameters to further refine results. Any filter key that conflicts with the pattern filter key is silently ignored — the pattern filter always takes precedence. Facets associated with fields used by the pattern filter are excluded from the response, as those dimensions are locked by the URL and cannot be changed by the user. servers: - url: https://{zone}-category-merchandising.doofinder.com/api/1 description: Category Merchandising API variables: zone: default: eu1 enum: - eu1 - us1 - ap1 description: >- Geographic zone of your search engine. Use the zone that matches your search engine region. security: - ApiToken: [] tags: - name: Category Merchandising description: Retrieve search results for a category page paths: /category_merchandising/{hashid}: get: tags: - Category Merchandising summary: Get category page results description: > Returns search results for the category page whose URL pattern matches the provided `url`. The `url` is matched against the URL patterns configured for the given search engine. The highest-priority matching pattern determines the base filter and facets applied to the search. Client-supplied `filter` params are merged on top: keys that overlap with the pattern filter are ignored, the rest are added to the query. **Sort order:** If `sort` params are provided they take precedence. Otherwise, the sort configured in the category page settings is applied. If neither is configured, results are returned in the engine's default order. operationId: getCategoryMerchandisingResults parameters: - name: hashid in: path required: true description: Search Engine ID (also known as hashid). schema: type: string example: abc1234de - name: url in: query required: true description: > Full URL of the category page to match against the configured URL patterns. Query string and fragment are stripped before matching. schema: type: string example: https://example.com/categories/shoes.html - name: currency in: query required: false description: > ISO 4217 currency code. When provided, prices are converted to this currency using the exchange rates configured in the search engine. schema: type: string example: EUR - name: page in: query required: false description: Page number (1-indexed). Defaults to `1`. schema: type: integer default: 1 minimum: 1 example: 2 - name: rpp in: query required: false description: Number of results per page. Defaults to `50`. schema: type: integer default: 50 minimum: 1 example: 24 - name: sort[N][field] in: query required: false description: > Sort criteria in indexed map format. `N` is a 0-based integer that defines the sort priority. `field` is the name of the field to sort by, and the value is the direction (`asc` or `desc`). Example: `sort[0][price]=asc&sort[1][brand]=desc` sorts first by price ascending, then by brand descending. If omitted, the sort configured in the category page settings is used. schema: type: string enum: - asc - desc - name: filter[field][] in: query required: false description: > Additional filter values to narrow the result set. `field` is the name of the indexed field. Repeat the parameter with different values to match any of them (OR logic within the same field). Example: `filter[brand][]=Nike&filter[brand][]=Adidas` Fields that conflict with the URL pattern filter are silently ignored. schema: type: array items: type: string - name: exclude[field][] in: query required: false description: > Exclude items with these field values from the results. `field` is the name of the indexed field. Repeat the parameter to exclude multiple values. Example: `exclude[dfid][]=abc123&exclude[dfid][]=def456` schema: type: array items: type: string - name: results_personalization_dfids[] in: query required: false description: > List of Doofinder item IDs (`dfid`) representing items the user has recently interacted with. When provided, results are reordered to surface contextually relevant items. schema: type: array items: type: string example: - abc1234de@product@a1b2c3 - abc1234de@product@d4e5f6 responses: '200': description: Search results for the matched category page. content: application/json: schema: $ref: '#/components/schemas/CategoryMerchandisingResponse' example: results: - dfid: abc1234de@product@a1b2c3 id: SKU-001 title: Running Shoes Model X price: 99.99 url: https://example.com/products/sku-001 image_url: https://example.com/images/sku-001.jpg - dfid: abc1234de@product@d4e5f6 id: SKU-002 title: Trail Running Shoes Y price: 129.99 url: https://example.com/products/sku-002 image_url: https://example.com/images/sku-002.jpg total: 243 page: 1 rpp: 50 facets: brand: _type: terms buckets: - key: Nike doc_count: 42 - key: Adidas doc_count: 38 price: _type: range buckets: - stats: min: 9.99 max: 499.99 avg: 89.5 base_filter: - field: category values: - shoes filter: [] banner: id: '189523' image: https://example.com/banners/shoes-banner.jpg mobile_image: https://example.com/banners/shoes-banner-mobile.jpg html_code: null link: https://example.com/sale/shoes target_blank: true '400': description: Bad Request — the required `url` query parameter is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: 'missing required param: url' '401': description: >- Unauthorized — the `Authorization` header is missing, the token is invalid, or the token does not have access to the requested search engine. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Authentication required '404': description: >- Not Found — the category page does not exist, is inactive, or no URL pattern matches the provided `url`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: not found '502': description: Bad Gateway — an upstream search engine error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: bad gateway components: schemas: CategoryMerchandisingResponse: type: object description: Search results and metadata for the matched category page. properties: results: type: array description: Ordered list of result items for the current page. items: $ref: '#/components/schemas/Item' total: type: integer description: >- Total number of items matching the effective filter (across all pages). example: 243 facets: type: object description: > Aggregations for the result set. Fields used by the URL pattern filter are excluded, as those dimensions cannot be changed by facet navigation. additionalProperties: $ref: '#/components/schemas/Facet' page: type: integer description: Current page number. example: 1 rpp: type: integer description: Number of results per page. example: 50 base_filter: type: array description: > The URL pattern filter applied to this category page, expressed as a list of field/values pairs. This filter is always present and is derived from the matched URL pattern. It cannot be overridden by client-supplied filters. items: $ref: '#/components/schemas/AppliedFilter' filter: type: array description: > The additional client-supplied filters applied to the search, expressed as a list of field/values pairs. This reflects only the filters passed by the caller via `filter[field][]=value` query parameters, excluding any keys that conflict with `base_filter`. items: $ref: '#/components/schemas/AppliedFilter' banner: $ref: '#/components/schemas/Banner' ErrorResponse: type: object properties: error: type: string description: Human-readable error message. example: 'missing required param: url' Item: type: object description: > A single result item from the search engine index. The fields returned depend on the index configuration of your search engine. `dfid`, `id`, `title`, `url`, and `image_url` are standard fields present in most indices. additionalProperties: true properties: dfid: type: string description: Doofinder's internal unique item identifier. example: abc1234de@product@a1b2c3 id: type: string description: Item identifier in the original catalog. example: SKU-001 title: type: string description: Item title. example: Running Shoes Model X description: type: string description: Item description. example: Lightweight running shoes for road and track. image_url: type: string description: URL of the item's main image. example: https://example.com/images/sku-001.jpg url: type: string description: URL of the item's product page. example: https://example.com/products/sku-001 price: type: number format: float description: Item price in the requested or default currency. example: 99.99 Facet: description: >- Aggregation data for a single field. Can be a term facet or a range facet. oneOf: - $ref: '#/components/schemas/TermFacet' - $ref: '#/components/schemas/RangeFacet' AppliedFilter: type: object description: A single filter term applied to the search query. properties: field: type: string description: The indexed field the filter is applied on. example: category values: type: array description: The values filtered by. Multiple values are combined with OR logic. items: type: string example: - shoes Banner: type: object nullable: true description: > A promotional banner associated with the current category filter, if one is configured. `null` when no banner is configured for the matched category. properties: id: type: string description: Banner identifier. example: '189523' image: type: string nullable: true description: URL of the banner image for desktop. example: https://example.com/banners/shoes-banner.jpg mobile_image: type: string nullable: true description: URL of the banner image for mobile devices. example: https://example.com/banners/shoes-banner-mobile.jpg html_code: type: string nullable: true description: >- Raw HTML content to render as the banner. When present, takes precedence over `image`. example:
Summer Sale — Up to 50% off shoes!
link: type: string nullable: true description: URL the banner links to when clicked. example: https://example.com/sale/shoes target_blank: type: boolean nullable: true description: Whether the banner link should open in a new browser tab. example: true TermFacet: type: object description: Facet with discrete term (keyword) values and their document counts. properties: _type: type: string enum: - terms example: terms buckets: type: array items: type: object properties: key: type: string description: The term value. example: Nike doc_count: type: integer description: Number of results with this value. example: 42 RangeFacet: type: object description: Facet with numeric range statistics (min, max, avg) for the result set. properties: _type: type: string enum: - range example: range buckets: type: array items: type: object properties: stats: type: object properties: min: type: number description: Minimum value in the result set. example: 9.99 max: type: number description: Maximum value in the result set. example: 499.99 avg: type: number description: Average value in the result set. example: 89.5 securitySchemes: ApiToken: type: apiKey in: header name: Authorization description: > API token in the format `Token {your_token}`. Required for server-side requests. Browser requests from allowed origins are authenticated automatically via CORS and do not need this token. ``` Authorization: Token abc123xyz ``` ````