POST
/
images
/
upload
Upload API: Image Upload for Search
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/images/upload \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '{}'
{
    "status": "success",
    "imageId": "550e8400-e29b-41d4-a716-446655440000"
}

Authorization

X-Storefront-Access-Token
string
required

Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

Headers

Content-Type
string
default:"multipart/form-data"
required
Accept
string
default:"application/json"
required

Body

image
file
required

Image file to upload. Supported formats: JPEG, JPG, PNG, WebP. Maximum file size: 15MB (15,360 KB).

Response

status
string

Status of the upload operation. Returns “success” on successful upload.

imageId
string

Unique UUID identifier for the uploaded image. Use this ID in the Image Search API to perform visual searches.

Usage

The Image Upload endpoint enables a two-step process for visual search:

  1. Upload the image using this endpoint to receive an imageId
  2. Search with the image using the imageId in the Image Search API

This approach offers several advantages:

  • Better performance: Avoids repeated base64 encoding/decoding
  • Caching: Processed image embeddings are cached for faster subsequent searches
  • Reduced payload size: Use lightweight UUID instead of large base64 strings

Error Responses

errors
object

Validation errors returned when the request fails validation.

Common validation errors:

  • File required: No image file provided
  • Invalid file type: File format not supported (must be JPEG, JPG, PNG, or WebP)
  • File too large: Image exceeds 15MB size limit
{
    "status": "success",
    "imageId": "550e8400-e29b-41d4-a716-446655440000"
}
{
    "message": "The given data was invalid.",
    "errors": {
        "image": [
            "The image field is required."
        ]
    }
}