API Reference

Integrate visual search capabilities directly into your application. All endpoints are served over HTTPS.

Authentication

The Visual Discovery API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard. Authentication to the API is performed via the Authorization header.

Header Example
Authorization: Bearer <YOUR_API_KEY>

Base URL

All requests to the Visual Discovery API should be issued to the following endpoint. We recommend pinning your requests to a specific version.

API Root
https://api.visualdiscovery.net/v1/discover

Errors

Visual Discovery uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with our servers.

Code Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing parameters or invalid image formats.
401 Unauthorized No valid API key provided.
404 Not Found The requested resource (e.g., request_id) does not exist.
429 Too Many Requests Too many requests hit the API too quickly.
500 Server Error Something went wrong on Visual Discovery's end.
POST

/detect

Uploads an image and runs neural object detection. Returns bounding boxes for all identified fashion items.

Request Body (multipart/form-data)

Parameter Type Description
file Binary The image file to analyze (JPG, PNG, WEBP). Max size 10MB.

Example Request

curl -X POST https://api.visualdiscovery.net/v1/discover/detect \
  -H "Authorization: Bearer KEY" \
  -F "account_id=ACCOUNT_ID_HERE" \
  -F "[email protected]"

Example Response

{
  "status": "success",
  "request_id": "req_12345",
  "detections": [
    {
      "label": "dress",
      "confidence": 0.98,
      "box": { "x1": 10, "y1": 20... },
      "image_url": "https://..."
    }
  ]
}
GET

/search

Performs a vector similarity search based on a specific crop from a previous detection request.

Query Parameters

Parameter Type Description
request_id String The ID returned from the /detect endpoint.
x1, y1, x2, y2 Integer Coordinates of the selected bounding box.
limit Integer Max results to return (default: 12).
search String Optional text keyword to filter results (e.g., "red").

Example Request

curl -G https://api.visualdiscovery.net/v1/discover/search \
  -d account_id=YOUR_ACCOUNT_ID \
  -d request_id=req_12345 \
  -d x1=10 -d y1=20 \
  -d x2=100 -d y2=200 \
  -d limit=12 -d search=

Example Response

{
  "status": "success",
  "similar_products": [
    {
      "id": "SKU-123",
      "name": "Floral Summer Dress",
      "similarity": 92.5,
      "price": 49.99,
      "url": "https://store.com/..."
    }
  ]
}
GET

/similar

Finds similar products to an existing inventory item.

Query Parameters

Parameter Type Description
account_id String Account ID of the customer.
id String The unique ID of the product (SKU) whose similarities are requested.
limit Integer Max results to return (default: 12).
search String Optional text keyword to filter results (e.g., "red").

Example Request

curl -G https://api.visualdiscovery.net/v1/discover/similar \
  -d account_id=YOUR_ACCOUNT_ID \
  -d id=SKU_123 \
  -d limit=12 -d search=

Example Response

{
  "status": "success",
  "similar_products": [
    {
      "id": "SKU-123",
      "name": "Floral Summer Dress",
      "similarity": 92.5,
      "price": 49.99,
      "url": "https://store.com/..."
    }
  ]
}
Read SDK & Integrations