> ## 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. # Search query (POST) > Search through indexed items of a search engine. Identical to the GET variant but accepts parameters as a JSON body, which is useful when query strings would be too long or when sending complex nested structures (filters, facets, sort). ## OpenAPI ````yaml /openapi/search-v6.yaml post /6/{hashid}/_search openapi: 3.0.0 info: title: Search API contact: name: Doofinder Support url: https://docs.doofinder.com/ version: '6.0' description: > # Introduction Search API allows you to perform the search requests you can do on your search engines using the doofinder layer, directly from your code. # Basics ## Endpoint All requests should be done with `https` protocol in our api location. `https://{search_zone}-search.doofinder.com` where `{search_zone}` depends on your location, is the geographic zone your search engine is located at. i.e.: eu1. Also, indicates which host to use in your API calls. ## Authentication The authentication method for search API requires an api key that could be obtained in our [management control panel](https://admin.doofinder.com). You can generate it in your user account -> Api Keys. Example of the generated API Key: `eu1-ab46030xza33960aac71a10248489b6c26172f07` ### API Token You could authenticate with the previous API key in header as a Token. The correct way to authenticate is to send a HTTP Header with the name `Authorization` and the value `Token ` For example, for the key shown above: `Authorization: Token eu1-ab46030xza33960aac71a10248489b6c26172f07` ## Client IP If you're calling this API directly from your own backend, rather than through Doofinder's JS layer, forward your end user's real IP address on every request, using one of: - `X-Real-IP` - `X-Forwarded-For` Without one of these headers, every request from your integration will appear to come from your server's single static IP address. Repeated requests from that one static IP can be flagged as bot traffic, which silently drops the affected search and click/session stats from your reports. It also skews any geographic breakdown in your stats, since it will be based on your server's location instead of your end users' locations. ## Conventions Along most of the code samples you will find placeholders for some common variable values. They are: - `{hashid}`: The search engine's unique id. i.e.: d8fdeab7fce96a19d3fc7b0ca7a1e98b - `{token}`: Your personal authentication token obtained in the control panel. - `{index}`: The index of the data you're searching at. i.e.: product - `{id}`: Unique identification of a resource. i.e.: 1234 or HVIUYC termsOfService: https://www.doofinder.com/es/terms-and-conditions x-logo: url: https://admin.doofinder.com/images/logo.svg backgroundColor: '#33268C' altText: Doofinder Search Engine servers: - url: https://{search_zone}-search.doofinder.com variables: search_zone: enum: - eu1 - us1 - ap1 default: eu1 - url: / security: - api_token: [] tags: - name: Search description: Search operations. - name: Session & Events description: Stats operations. paths: /6/{hashid}/_search: post: tags: - Search summary: Search query (POST) description: | Search through indexed items of a search engine. Identical to the GET variant but accepts parameters as a JSON body, which is useful when query strings would be too long or when sending complex nested structures (filters, facets, sort). operationId: search_query_post parameters: - $ref: '#/components/parameters/hashid' requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: >- Bad Request — invalid query parameters (invalid rpp, page, query_name, sort, filter_execution, session_id, or user_id). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_query: summary: Bad query value value: error: Bad request, bad query invalid_session_id: summary: session_id too long value: error: session_id should have 32 characters or less invalid_rpp: summary: Invalid rpp value: error: Invalid rpp '403': description: >- Forbidden — missing or invalid API token, client IP is blocked, or CORS `Origin` not allowed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Missing or invalid API token value: error: forbidden banned_ip: summary: Client IP is blocked value: error: banned ip '404': description: Not Found — search engine mapping does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: summary: Mapping not found value: error: Mapping not found components: parameters: hashid: name: hashid in: path description: Unique id of a search engine. required: true schema: type: string schemas: SearchRequest: type: object description: Search parameters sent as a JSON body. All fields are optional. properties: query: type: string description: The search term. Cannot be longer than 200 characters or 10 words. rpp: type: integer description: Results per page (max 100, rpp * page < 1000). page: type: integer description: Page number of the results to return. indices: type: array items: type: string description: >- Restrict the search to one or more indices (e.g. ["product", "page"]). filter: type: object description: > Filter parameters for items. Keys are field names, values are lists of terms or range objects (gte, lte, gt, lt). additionalProperties: true exclude: type: object description: Negative filters. Same structure as filter. additionalProperties: true facets: type: array description: Aggregations to compute. Each entry must include a "field" key. items: type: object properties: field: type: string size: type: integer type: type: string enum: - term - range filter_execution: type: string enum: - and - or description: Boolean logic applied to filters. Default is "and". sort: type: array description: | Sort criteria. Each entry is a map of field name to direction (e.g. [{"price": "asc"}]). items: type: object additionalProperties: type: string query_name: type: string enum: - match_and - match_or - fuzzy description: Force a specific query type. session_id: $ref: '#/components/schemas/session_id' user_id: $ref: '#/components/schemas/user_id' stats: type: boolean description: 'Enable/Disable this search in stats reports. Default: true' auto_filters: type: boolean description: 'Enable/Disable auto filters feature. Default: false' custom_results: type: boolean description: 'Enable/Disable custom results feature. Default: true' excluded_results: type: boolean description: 'Enable/Disable excluded items feature. Default: true' grouping: type: boolean description: Enable/Disable grouping of variants as single items. with_variants: type: array items: type: string description: > When grouping is active, include a df_variants array in each hit with the listed fields from each variant document. skip_auto_filters: type: array items: type: string description: Fields to exclude from auto_filters processing. skip_top_facet: type: array items: type: string description: Fields to exclude from top_facet processing. top_facet: type: boolean description: 'Enable/Disable top_facet feature. Default: false' SearchResponse: title: Search Response description: | Search response. Some fields can not be included in the request if they have not data. type: object properties: banner: $ref: '#/components/schemas/BannerResponse' count: description: | Total number of items found in the search engine for the searched term. type: integer custom_results_id: type: integer description: | Id of applied custom results. This field will not be included if none of the custom results apply. dynamic_boosting_rule_id: type: integer description: | Id of applied dynamic boosting rule. This field will not be included if none of the dynamic boosting rules apply. facets: description: >- Information about different groupings that can be made for certain fields in the search results. items: oneOf: - $ref: '#/components/schemas/TermFacetResponse' - $ref: '#/components/schemas/RangeFacetResponse' type: array query_name: type: string description: >- In order to get the best possible results, Doofinder tries several types of querying. This is the type of the query Doofinder made to obtain these results. results: items: $ref: '#/components/schemas/Item' type: array total: type: integer description: Total number of items that can be fetched. example: custom_results_id: 5 facets: - brand: terms: items: - name: Adidas count: 5 - name: Nike count: 3 selected: [] query_name: fuzzy results: - description: The best product description ever dfid: 1234567890abcdef1234567890abcdef@product@1234567890abcdef id: my_id image_url: http://www.example.com/images/alt_product_image.jpg title: My item url: http://www.example.com/alt_product_description.htm total: 1 ErrorResponse: type: object description: Standard error response returned on all non-200 outcomes. properties: error: type: string description: Human-readable error message. required: - error session_id: type: string description: Identifier of search session maxLength: 32 user_id: type: string description: Identifier of user maxLength: 36 BannerResponse: title: Banner Response description: Banner response for a query search. type: object properties: blank: description: Display the banner link in a new window. type: boolean html_code: description: Html code to be used as banner instead of an image. type: string id: description: Banner identification. type: integer image: description: Image URL used as banner. type: string link: description: URL to be redirected when click over banner. type: string mobile_image: description: Image URL used as banner for mobile devices. type: string TermFacetResponse: title: Term Facet Response description: Facet terms search response. Used to aggregate a field by their values. type: object properties: key: description: Name of the aggregated field. type: string terms: type: object description: Facet terms list properties: items: type: array items: type: object properties: count: description: Number of elements type: integer name: description: Name of the term type: string selected: description: Items that are selected as part of a filter. type: array items: type: object properties: count: description: Number of elements type: integer name: description: Name of the term type: string RangeFacetResponse: title: Range Facet Response description: | Facet range search response. Used to return the min and max values for the aggregated field. type: object properties: key: description: Name of the aggregated field. type: string range: type: object properties: from: description: Selected start point of the range. type: number max: description: Maximum value of the field. type: number min: description: Minimum value of the field. type: number to: description: Selected end point of the range. type: number Item: title: Item description: A searchable object. Items are the objects that form the search results. type: object properties: description: type: string description: Item description. dfid: type: string description: >- Doofinder result doofinder id. It comes in every Doofinder results for every item. id: type: string description: Unique identification of an indexed item. image_url: type: string description: Item image url. title: type: string description: Item title. url: type: string description: Item url. required: - dfid - id - title example: description: The best product description ever dfid: 1234567890abcdef1234567890abcdef@product@1234567890abcdef id: my_id image_url: http://www.example.com/images/alt_product_image.jpg title: My item url: http://www.example.com/alt_product_description.htm securitySchemes: api_token: type: apiKey name: Authorization in: header description: > Doofinder API key. The `Token` prefix is part of the header value, so enter it too — the field is sent verbatim as: Authorization: Token x-default: Token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.