🖼️ Visual Search

To search by external query image, upload external the image and make it
available as a query image by issuing the following call:

Upload an Image for Search

POST /api/v1/dataset/{dataset-id}/search-image-similarity?entity_type=IMAGES&bounding_box=X,Y,WIDTH,HEIGHT
Headers: Authorization: Bearer <jwt>

Request Parameters:

file: Query image file
bounding_box (optional): X, Y, Width, Height

Visual Layer API - Dataset Exploration

After uploading the image you can call exploration endpoint with anchor media id:

GET /api/v1/explore/{dataset-id}

GET /api/v1/explore/{dataset-id}?threshold=0&anchor_type={anchor_type}&entity_type={ENTITY_TYPE}&page_number={PAGE_NUMBER}&anchor_media_id={anchor_media_id}
Headers: Authorization: Bearer <jwt>

🧾 Query Parameters

ENTITY TYPE either IMAGES or OBJECTS
anchor_type, anchor_media_id from previous endpoint response

📦 Sample Response

  {  
    "clusters": \[  
      {  
        "id": "4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b",  
        "dataset_id": "95233006-eddc-11ef-b303-76dbc3993eb2",  
        "cluster_type": "IMAGES",  
        "display_name": "Cluster 1",  
        "n_images": 5,  
        "n_objects": 0,  
        "size_bytes": 1024000,  
        "similarity_threshold": 2,  
        "formed_by": "connected_components",  
        "previews": \[  
          {  
            "id": "9e8da312-d954-4844-afc7-357c458c5b03",  
            "image_id": "9e8da312-d954-4844-afc7-357c458c5b03",  
            "image_uri": "/api/v1/image/9e8da312-d954-4844-afc7-357c458c5b03",  
            "width": 800,  
            "height": 600,  
            "image_type": "jpeg",  
            "order": 1,  
            "labels": ["cat", "pet"],  
            "caption": "A gray cat lying on a sofa",  
            "thumbnail_uri": "/api/v1/image/9e8da312-d954-4844-afc7-357c458c5b03/thumbnail"  
          }  
        ],  
        "parent_id": null,  
        "cluster_path": ["4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b"],  
        "image_order": "similarity"  
      }  
    ]  
  }

Example:

curl -H "Authorization: Bearer <jwt>" https://app.visual-layer.com/api/v1/explore/{dataset-id}?threshold=0&entity_type=IMAGES&page_number=0&anchor_media_id={anchor_media_id}

📝Notes:

Results are paginated with a fixed page size of 100 clusters per page
Higher threshold values (0-4) create more granular clusters with stricter similarity requirements
When using anchor-based similarity search, results are ordered by similarity to the anchor
The entity_type parameter controls whether to return image clusters, object clusters, or both
For similarity search with an uploaded image, first use the /search-image-similarity endpoint

More detailed example is here