> ## 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` ## 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. title_facet: type: boolean description: 'Enable/Disable title_facet feature. Default: false' 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 description: | Doofinder API key. Pass it as: Authorization: Token name: Authorization in: header ````