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."
        ]
    }
}