# Image Search

Image-based product discovery

## Search products by image URL

> Searches for products similar to the provided image using an external\
> search service. The image is fetched from the provided URL and analyzed\
> for visual similarity with indexed product images.\
> \
> This endpoint requires the external search extension to be enabled\
> through the EXTERNAL\_SEARCH\_EXTENSION\_CONFIG dynamic setting. When\
> disabled, this endpoint returns a 404 Not Found response.\
> \
> The search can be refined by providing optional text keywords and\
> excluding specific product identifiers from the results.\
> \
> Rate limiting applies to prevent abuse of this endpoint.\
> \
> \*\*Image Requirements:\*\*\
> \- Image must be accessible via the provided URL\
> \- Image dimensions must be less than the configured maximum\
>   (default: 2000x2000 pixels)

```json
{"openapi":"3.1.0","info":{"title":"Search API - Product Discovery & Image Search","version":"1.0.0"},"tags":[{"name":"Image Search","description":"Image-based product discovery"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/image-search/":{"get":{"tags":["Image Search"],"operationId":"searchProductsByImageUrl","summary":"Search products by image URL","description":"Searches for products similar to the provided image using an external\nsearch service. The image is fetched from the provided URL and analyzed\nfor visual similarity with indexed product images.\n\nThis endpoint requires the external search extension to be enabled\nthrough the EXTERNAL_SEARCH_EXTENSION_CONFIG dynamic setting. When\ndisabled, this endpoint returns a 404 Not Found response.\n\nThe search can be refined by providing optional text keywords and\nexcluding specific product identifiers from the results.\n\nRate limiting applies to prevent abuse of this endpoint.\n\n**Image Requirements:**\n- Image must be accessible via the provided URL\n- Image dimensions must be less than the configured maximum\n  (default: 2000x2000 pixels)","parameters":[{"$ref":"#/components/parameters/ImageUrlParameter"},{"$ref":"#/components/parameters/ExcludedProductIdsQueryParameter"},{"$ref":"#/components/parameters/ImageSearchTextParameter"}],"responses":{"200":{"description":"Image search completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}},"400":{"$ref":"#/components/responses/ValidationErrorResponse"},"404":{"description":"External search extension not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/ErrorResponse"}}}}},"components":{"parameters":{"ImageUrlParameter":{"name":"url","in":"query","required":true,"description":"URL of the image to search for","schema":{"type":"string","format":"uri"}},"ExcludedProductIdsQueryParameter":{"name":"excluded_product_ids","in":"query","description":"Comma-separated list of product identifiers to exclude from results","required":false,"schema":{"type":"string"}},"ImageSearchTextParameter":{"name":"text","in":"query","description":"Optional text keywords to refine the image search","required":false,"schema":{"type":"string","maxLength":5000}}},"schemas":{"ImageSearchResponse":{"type":"object","description":"Image search results","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"List of product identifiers matching the image","items":{"type":"integer"}}}},"ValidationErrorResponse":{"type":"object","description":"Validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"Error message"}}}},"responses":{"ValidationErrorResponse":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"ErrorResponse":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

## Search products by base64 image

> Searches for products similar to the provided base64-encoded image\
> using an external search service. The image is decoded and analyzed\
> for visual similarity with indexed product images.\
> \
> This endpoint requires the external search extension to be enabled\
> through the EXTERNAL\_SEARCH\_EXTENSION\_CONFIG dynamic setting. When\
> disabled, this endpoint returns a 404 Not Found response.\
> \
> The search can be refined by providing optional text keywords and\
> excluding specific product identifiers from the results.\
> \
> Rate limiting applies to prevent abuse of this endpoint.\
> \
> \*\*Image Requirements:\*\*\
> \- Image must be valid base64-encoded data\
> \- Image must be a valid image format (JPEG, PNG, JPG, WEBP.)\
> \- Image file size must not exceed the configured maximum\
>   (default: 5MB)\
> \- Image dimensions must be less than the configured maximum\
>   (default: 2000x2000 pixels)

```json
{"openapi":"3.1.0","info":{"title":"Search API - Product Discovery & Image Search","version":"1.0.0"},"tags":[{"name":"Image Search","description":"Image-based product discovery"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/image-search/":{"post":{"tags":["Image Search"],"operationId":"searchProductsByImageBase64","summary":"Search products by base64 image","description":"Searches for products similar to the provided base64-encoded image\nusing an external search service. The image is decoded and analyzed\nfor visual similarity with indexed product images.\n\nThis endpoint requires the external search extension to be enabled\nthrough the EXTERNAL_SEARCH_EXTENSION_CONFIG dynamic setting. When\ndisabled, this endpoint returns a 404 Not Found response.\n\nThe search can be refined by providing optional text keywords and\nexcluding specific product identifiers from the results.\n\nRate limiting applies to prevent abuse of this endpoint.\n\n**Image Requirements:**\n- Image must be valid base64-encoded data\n- Image must be a valid image format (JPEG, PNG, JPG, WEBP.)\n- Image file size must not exceed the configured maximum\n  (default: 5MB)\n- Image dimensions must be less than the configured maximum\n  (default: 2000x2000 pixels)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchRequest"}}}},"responses":{"200":{"description":"Image search completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}},"400":{"$ref":"#/components/responses/ValidationErrorResponse"},"404":{"description":"External search extension not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/ErrorResponse"}}}}},"components":{"schemas":{"ImageSearchRequest":{"type":"object","description":"Request payload for base64 image search","required":["image"],"properties":{"image":{"type":"string","description":"Base64-encoded image data. Must be a valid image format (JPEG, PNG, etc.).\nThe decoded image must be smaller than the configured maximum file size\nand have dimensions less than the configured maximum.\n"},"excluded_product_ids":{"type":"array","description":"Product identifiers to exclude from results","items":{"type":"integer"}},"text":{"type":"string","description":"Optional text keywords to refine the image search","maxLength":5000}}},"ImageSearchResponse":{"type":"object","description":"Image search results","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"List of product identifiers matching the image","items":{"type":"integer"}}}},"ValidationErrorResponse":{"type":"object","description":"Validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"Error message"}}}},"responses":{"ValidationErrorResponse":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"ErrorResponse":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```