Skip to main content
The Visual Layer API provides programmatic access to dataset management, visual search, semantic search, enrichment, and export capabilities. All endpoints are REST-based and return JSON.

​
Cloud API vs. On-Premises API

Authentication requirements differ by deployment type.
  • Cloud API: All calls require a JWT bearer token. See Authentication.
  • On-Premises API: Authentication is not required. Omit authorization headers from all requests.

​
Create a Dataset

Datasets can be created from an S3 bucket path, from local file uploads, or from a local folder on an on-premises installation. After creation, poll the dataset status endpoint until status_new reaches READY. See Create a Dataset from S3, Create a Dataset from Local Files, and Retrieve Dataset Status.
Two search modes are available through the Explore endpoint (GET /api/v1/explore/{dataset_id}). Visual Search finds images visually similar to a query image. Upload the query image to get an anchor_media_id, then pass it to the Explore endpoint. See Visual Search. Semantic Search finds images using natural language. Pass a caption query parameter or use VQL text filters for more control. See Semantic Search.

​
Manage Datasets

  • Add media to an existing dataset from S3, direct upload, or archive. See Add Media to an Existing Dataset.
  • Share a dataset with another registered user. See Share a Dataset.
  • Enrich a dataset with AI models to generate captions, detect objects, and build search embeddings. Enrichment creates a new dataset copy. See Enrichment.
  • Save views to bookmark filtered states for reuse. See Saved Views.

​
Export

Export dataset metadata and media as JSON or Parquet, either in full or selectively by media ID or cluster. See Exporting a Dataset.

​
Error Handling

All API errors return a JSON body with a detail field. See Error Handling for the full HTTP code reference, error response format, and Python handling patterns.