> ## 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. # Image Search > Search through indexed images of a search engine. ## OpenAPI ````yaml /openapi/search-v6.yaml post /6/{hashid}/_image_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}/_image_search: post: tags: - Search summary: Image Search description: Search through indexed images of a search engine. operationId: image_search_query parameters: - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/excluded_results' - $ref: '#/components/parameters/facets' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/filter_execution' - $ref: '#/components/parameters/hashid' - $ref: '#/components/parameters/rpp' - $ref: '#/components/parameters/session_id_query' - $ref: '#/components/parameters/user_id_query' - $ref: '#/components/parameters/stats' - $ref: '#/components/parameters/sort' requestBody: content: application/json: schema: $ref: '#/components/schemas/ImageSearchRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: >- Bad Request — `image` field missing, invalid `rpp`, or image search is not enabled for this search engine. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_image: summary: image field missing value: error: 'Following fields are missing: ["image"]' not_enabled: summary: Feature not enabled value: error: Image Search is not enabled for this search engine invalid_rpp: summary: Invalid rpp value 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 '424': description: >- Failed Dependency — the image embedding service returned an error. Retry the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: summary: Image embedding failed value: error: >- There was an error obtaining the embeddings, please try again. components: parameters: exclude: name: exclude in: query description: > Exclusive parameters are negative filters. Doofinder expects the exclude parameters grouped like this: `exclude: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }` For the range filters it can be used the following: - gte: Greater than or equal - lte: Less than or equal - gt: Greater than - lt: Less than Writing that down in request parameters language is: `exclude[color][]=blue&exclude[color][]=red&exclude[size]=M&exclude[size]=S&exclude[price][gte]=4.36&exclude[price][lt]=99` Note that [ and ] characters should be escaped (%5B and %5D) in all exclude cases. schema: type: string excluded_results: name: excluded_results in: query description: 'Enable/Disable excluded items feature in the search. Default: true' schema: type: boolean facets: name: facets in: query schema: type: object description: > Aggregates fields values in a facet, you could use a term facet or range facet. Read [facets configuration](https://support.doofinder.com/search/layer-settings/filters-configuration) for more deep info about facets. The type of the facet (term or range) will be determined automatically. Parameters: * __field__*: That is the field name that you want to aggregate results. * size: The number of results to return in each field. Only applicable to facet terms. Maximum: 50 by default to help maintain the speed of the search function. If you need more, please contact Doofinder support. * type: The facet type. Indicates the type of the facet, one of `term` or `range`. will return an error if the facet type is not correct. *required parameter Example request returning the `brand` term facet and the `best_facet` range facet: `facets[0][field]=brand&facets[0][size]=10&facets[1][field]=best_price`. filter: name: filter in: query description: > Filter parameters for items. Doofinder expects the filter parameters grouped like this: `filter: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }` Range filters can be used as follow: - gte: Greater than or equal - lte: Less than or equal - gt: Greater than - lt: Less than Writing that down in request parameters language: `filter[color][]=blue&filter[color][]=red&filter[size][]=M&filter[size][]=S&filter[price][gte]=4.36&filter[price][lt]=99` Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases. schema: type: string filter_execution: name: filter_execution in: query description: > Filters are applied with "and" boolean logic than means that all filters conditions should be met. If you want to apply any of the filters conditions, you can change it to "or". schema: type: string enum: - and - or hashid: name: hashid in: path description: Unique id of a search engine. required: true schema: type: string rpp: name: rpp in: query description: | Results per page. how many results per page to return. Limits are rpp <= 100 and rpp * page < 1000. schema: type: integer session_id_query: name: session_id in: query description: The current session ID, must be unique for each user. schema: $ref: '#/components/schemas/session_id' user_id_query: name: user_id in: query description: Identifies the user, must be unique for each user. schema: $ref: '#/components/schemas/user_id' stats: name: stats in: query description: 'Enable/Disable this search in stats reports. Default: true' schema: type: boolean sort: name: sort in: query description: > Sorted results by certain fields. Doofinder expects sort parameters like this: `sort: [{"price": "asc"}, {"brand": "desc"}]` Writing that down in request parameters language is: `sort[0][price]=asc&sort[1][brand]=desc` Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases. schema: type: string schemas: ImageSearchRequest: type: object properties: image: type: string format: base64 description: Image encoded in base64. example: iVBORw0KGgoAAAANSUhEUgAAAboAAAC7CAYAAAAT... required: - image 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 ````