API docs by Redocly

USD Search and Asset Graph Search APIs (1.5.0)

Download OpenAPI specification:

USD Search API Overview

USD Search API is a collection of cloud-native microservices that enable developers, creators, and workflow specialists to efficiently search through vast collections of OpenUSD data, images, and other assets using natural language or image-based inputs. With these production-ready microservices, developers can deploy USD Search API onto their own infrastructure. With USD Search API’s artificial intelligence (AI) features, you can quickly locate untagged and unstructured 3D data and digital assets, saving time navigating unstructured, untagged 3D data. USD Search API is capable of searching and indexing 3D asset databases, as well as navigating complex 3D scenes to perform spatial searches, without requiring manual tagging of assets.

Features

  • Natural Language Searches: - Utilize AI to search for images and USD-based 3D models using simple, descriptive language.
  • Image Similarity Searches: - Find images similar to a reference image through AI-driven image comparisons.
  • Metadata Filtering: - Filter search results by file name, file type, creation/modification dates, file size, and creator/modifier metadata.
  • USD Content Filtering with Asset Graph Search: - When used with the Asset Graph Search, search capabilities are expanded to include filtering based on USD properties and object dimensions.
  • Multiple Storage Backend Support: - Compatible with various storage backends, including AWS S3 buckets and Omniverse Nucleus server.
  • Advanced File Name, Extension, and Path Filters: - Use wildcards for broad or specific file name and extension searches.
  • Date and Size Range Filtering: - Specify assets created or modified within certain date ranges or file sizes larger or smaller than a designated threshold.
  • User-based Filtering: - Filter assets based on their creator or modifier, allowing for searches tailored to particular users' contributions.
  • Embedding-based Similarity Threshold: - Set a similarity threshold for more nuanced control over search results in embedding-based searches.
  • Custom Search Paths and Scenes: - Specify search locations within the storage backend or conduct searches within specific scenes for targeted results.
  • Return Detailed Results: - Option to include images, metadata, root prims, and predictions in the search results.

Asset Graph Search (AGS) API Overview

Asset Graph Search (AGS) provides advanced querying capabilities for assets and USD trees indexed in a graph database. It supports proximity queries based on coordinates or prims to find objects within specified areas or radii, sorted by distance, and includes transformation options for vector alignment. The API also offers dependency and reverse dependency searches, helping to identify all assets referenced in a scene or scenes containing a particular asset, which can optimize scene loading and track dependency changes. By combining different query types, the AGS API enables complex scenarios for scene understanding, manipulation, and generation. Integrated with USD Search it provides in-scene search functionality.

Features

  • Proximity Queries: - Find objects within a specified bounding box or radius. - Results sorted by distance with options for vector alignment using a transformation matrix.
  • USD Property Queries: - Enables querying objects in a 3D scene using USD properties, such as finding all assets with a specific semantic label.
  • Asset Dependency Searches: - Identify all assets referenced in a scene — including USD references, material references, or textures. - Reverse search to find all scenes containing a particular asset.
  • Combined Query Capabilities: - Enable complex scenarios for enhanced scene understanding, manipulation, and generation.
  • Integration with USD Search: - Provides in-scene search functionality.

AGS Spatial Graph

Spatial graph queries APIs.

Get Prims Within Radius

Find all objects near a point or another object within a USD scene.

Use this endpoint when you need to answer spatial questions like "find all objects within 5 meters of the table" or "what's near coordinates (10, 0, 5) in this scene". Returns prims sorted by distance from the query center, including their bounding boxes, properties, and the direction vector to each result.

Perform a spatial search within a scene to retrieve prims from a USD scene based on their proximity to a reference prim center_prim_usd_path or specific coordinates [center_x, center_y, center_z] within a specified radius.

Note: You must specify either center_prim_usd_path or the coordinates [center_x, center_y, center_z].

Returns prim objects including: attributes, dimensions, and min, max, midpoint coordinates of the bounding box, distance from the query center, vector from the query center to the prim midpoint.

If searching using center_prim_usd_path the center prim at center_prim_usd_path is included in the results (unless excluded by filters used).

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

URL of the scene to search.

radius
required
number (Radius) > 0

Radius of the proximity query

center_prim_usd_path
string (Center Prim Usd Path)

USD path of the reference Prim. (Returned in results unless excluded by filters)

center_x
number (Center X)

X coordinate of the query center.

center_y
number (Center Y)

Y coordinate of the query center.

center_z
number (Center Z)

Z coordinate of the query center.

transformation_matrix
string (Transformation Matrix)
Default: "1,0,0;0,1,0;0,0,1"

Transformation matrix for the vector space. By default does not apply any transformation.

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)
Default: 4e+38

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)
Default: 4e+38

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)
Default: 4e+38

Max bounding box Z dimension

Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions)
Default: false

Search in the space of aligned bbox dimensions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Prims Within Bounding Box

Find all objects within a rectangular region of a USD scene.

Use this endpoint when you need to find objects in a specific area, e.g., "find all objects in the kitchen area" or "what's in the region between coordinates (0,0,0) and (10,5,10)". A prim is included if its bounding box midpoint falls within the query bounding box.

The bounding box is defined by two corner points: [min_bbox_x, min_bbox_y, min_bbox_z] and [max_bbox_x, max_bbox_y, max_bbox_z].

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

Retrieve prims from the scene at specified URL.

min_bbox_x
required
number (Min Bbox X)

Query bounding box minimum X

min_bbox_y
required
number (Min Bbox Y)

Query bounding box minimum Y

min_bbox_z
required
number (Min Bbox Z)

Query bounding box minimum Z

max_bbox_x
required
number (Max Bbox X)

Query bounding box maximum X

max_bbox_y
required
number (Max Bbox Y)

Query bounding box maximum Y

max_bbox_z
required
number (Max Bbox Z)

Query bounding box maximum Z

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)
Default: 4e+38

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)
Default: 4e+38

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)
Default: 4e+38

Max bounding box Z dimension

Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions)
Default: false

Search in the space of aligned bbox dimensions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

AGS Scene Graph

Scene graph queries APIs.

Get Prims

Retrieve and filter prims from a USD scene — use for scene understanding and object enumeration.

Use this endpoint when you need to understand what objects are in a scene, filter by type or properties, or retrieve specific prims by their USD path. Returns all matching prims with their locations, dimensions, and properties. Ideal for answering "what objects are in this scene?" or "find all Mesh prims with class=vehicle".

NOTE: Calling without any parameters will return ALL prims. scene_url must be provided to fetch prims from the specified scene.

A globally unique prim id consists of (scene_url, usd_path) tuple. usd_path is unique only within a single scene. To retrieve prims from a specified scene, scene_url must be set. To retrieve a single prim from a specified scene, provide both scene_url and usd_path.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
string (Scene Url)

Retrieve prims from the scene at specified URL.

Array of Usd Path (strings) or Usd Path (string) (Usd Path)
Examples:
  • - Any USD path
  • usd_path=/Root - Root prim
  • usd_path=Path1&usd_path=Path2&usd_path=Path3 - Multiple USD paths

Retrieve prims from the specified USD paths. Can provide either a single path or a list of paths.

root_prim
boolean (Root Prim)

Retrieve root prims. Note: combined with default_prim returns both root and default prims. Works as inclusive filter only; setting to false has no effect.

default_prim
boolean (Default Prim)

Retrieve default prims. Note: combined with root_prim returns both root and default prims. Works as inclusive filter only; setting to false has no effect.

source_asset_url
string (Source Asset Url)

Filter prims based on their source asset URL, i.e. the asset they have a reference to

limit
integer (Limit) > 0
Default: 1000

Page size

Array of Prim Type (strings) or Prim Type (null) (Prim Type)
Examples:
  • - Any prim type
  • prim_type=Xform - Xform prim type
  • prim_type=Xform&prim_type=Mesh - Xform and Mesh prim types

Retrieve prims of the specified types.

Usd Path Prefix (string) or Usd Path Prefix (null) (Usd Path Prefix)
Examples:
  • - Any USD path
  • usd_path_prefix=/Root - Root prim
  • usd_path_prefix=/Root/Car - /Root/Car

Retrieve prims with USD paths that begin with this prefix (i.e., the children of the prim at the specified path).

Properties Filter (string) or Properties Filter (null) (Properties Filter)
Examples:
  • - Any attribute
  • properties_filter=class=lamp - Prims labeled class=lamp

Filter prims based on USD attributes (note: only a subset of attributes configured in the indexing service is available). Format: attribute1=abc,attribute2=456

Min Bbox Dimension X (number) or Min Bbox Dimension X (null) (Min Bbox Dimension X)

Minimum bounding box X dimension

Min Bbox Dimension Y (number) or Min Bbox Dimension Y (null) (Min Bbox Dimension Y)

Minimum bounding box Y dimension

Min Bbox Dimension Z (number) or Min Bbox Dimension Z (null) (Min Bbox Dimension Z)

Minimum bounding box Z dimension

Max Bbox Dimension X (number) or Max Bbox Dimension X (null) (Max Bbox Dimension X)

Max bounding box X dimension

Max Bbox Dimension Y (number) or Max Bbox Dimension Y (null) (Max Bbox Dimension Y)

Max bounding box Y dimension

Max Bbox Dimension Z (number) or Max Bbox Dimension Z (null) (Max Bbox Dimension Z)

Max bounding box Z dimension

Use Scaled Bbox Dimensions (boolean) or Use Scaled Bbox Dimensions (null) (Use Scaled Bbox Dimensions)
Default: true

Search in the space of MPU aligned bbox dimensions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Scene Summary

Get a quick overview of scene contents — use before detailed spatial or prim queries.

Use this endpoint to understand a scene's composition: how many prims, what types (Mesh, Xform, etc.), what properties are used, what assets are referenced, total polygon count, and scene metadata (MPU, up axis). Ideal first call when exploring an unfamiliar scene.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
scene_url
required
string (Scene Url)

Scene summary.

Responses

Response samples

Content type
application/json
{
  • "scene_url": "string",
  • "scene_mpu": 0,
  • "scene_up_axis": "X",
  • "n_prims": 0,
  • "total_polygon_count": 0,
  • "total_point_count": 0,
  • "total_curve_segment_count": 0,
  • "prim_types": {
    },
  • "unique_property_keys": {
    },
  • "unique_properties": {
    },
  • "referenced_assets": {
    },
  • "default_prim": {
    }
}

AGS Asset Graph

Asset graph/dependencies graph queries APIs.

Get Dependencies Graph

Get the full dependency tree of an asset as a graph — use to discover sub-assemblies, textures, and materials.

Use this endpoint when you need to understand what files an asset references (e.g., "what textures does this car model use?" or "what sub-assets make up this scene?"). Returns nodes (assets) and directed edges (dependency relationships). Traverses references recursively up to max_level depth.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Get Dependencies Flat

Get a flat list of all files an asset depends on — simpler alternative to the graph endpoint.

Use this endpoint when you just need the list of referenced files without graph structure (e.g., "list all textures used by this model"). Returns Asset objects with URLs. For graph structure with edges, use GET /dependency_graph/graph instead.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Dependencies Inverse

Find which scenes or assets reference a given asset — use for impact analysis.

Use this endpoint to answer "where is this asset used?" or "which scenes reference this texture?". Returns a flat list of all assets that depend on (reference) the specified asset. Useful for impact analysis before modifying or deleting an asset.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Inverse Dependencies Graph

Get the full reverse dependency graph — all assets that directly or transitively reference the specified asset.

Use this endpoint for impact analysis with full graph structure (nodes + edges), e.g., "show me the full dependency chain of everything that uses this material". For a simpler flat list, use GET /dependency_graph/inverse/flat instead.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
root_node_url
required
string (Root Node Url)

URL of the asset

max_level
integer (Max Level) > 0

Max level of dependency tree traversal (by default unlimited)

limit
integer (Limit) > 0
Default: 1000

Page size

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ]
}

Search

All supported search parameters are available as query parameters.

Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Service, USD Search API extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.

Pagination: pass offset, or better, the previous response's X-Next-Cursor header back as cursor — it pins the ranking so pages do not overlap or skip. Because this endpoint returns a bare JSON array, the pagination state travels in response headers rather than the body: X-Next-Cursor, X-Has-More (true/false) and X-Paginable-Total (the page-count basis). How deep you can go depends on the query shape: filter-only queries are unbounded, a text query is capped by the deployment's pagination_max_offset, and a multi-leg query is capped by the RRF fusion window. validate_results=true is single-page and cannot be combined with offset/cursor. The richer envelope — including why paging stopped — is on POST /v3/deepsearch/search.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
description
string (Description) <= 1024 characters
Default: ""
Examples:
  • - No text-based search
  • description=box - Example search for 'box'
  • description=pallet - Example search for 'pallet'
  • description=red rusty barrel - Example search for 'red rusty barrel'

Conduct text-based searches powered by AI

Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search)
Examples:
  • - No image similarity search
  • image_similarity_search=iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC - Base64 encoded image example
  • image_similarity_search=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC - Base64 encoded image with format prefix example
  • image_similarity_search=s3://bucket-name/Project/asset1.usd - Storage backend URL example

Perform similarity searches based on a list of images

file_name
string (File Name)
Default: ""
Examples:
  • file_name=robot.usd - Example to find files matching 'robot.usd'
  • file_name=*scene* - Example to find files partially matching 'scene'

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_file_name
string (Exclude File Name)
Default: ""
Examples:
  • exclude_file_name=draft* - Example to exclude files with 'draft' prefix
  • exclude_file_name=*temp* - Example to exclude files with 'temp' in their names

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_include
string (File Extension Include)
Default: ""
Examples:
  • file_extension_include=usd - Example to filter for '.usd' files
  • file_extension_include=usd* - Example to filter for all types of USD files
  • file_extension_include=jpg - Example to filter for '.jpg' files
  • file_extension_include=jpg,png,gif - Example to filter for image files

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

file_extension_exclude
string (File Extension Exclude)
Default: ""
Examples:
  • file_extension_exclude=jpg - Example to exclude '.jpg' files
  • file_extension_exclude=jpg,png,gif - Example to exclude image files
  • file_extension_exclude=mdl - Example to exclude '.mdl' files

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Created After (string) or Created After (null) (Created After)
Examples:
  • - Disable created_after filter
  • created_after=2023-01-01 - Example to filter assets created after '2023-01-01'
  • created_after=2023-06-01 - Example to filter assets created after '2023-06-01'

Filter results to only include assets created after a specified date

Created Before (string) or Created Before (null) (Created Before)
Examples:
  • - Disable created_before filter
  • created_before=2023-01-01 - Example to filter assets created before '2023-01-01'
  • created_before=2023-06-01 - Example to filter assets created before '2023-06-01'

Filter results to only include assets created before a specified date

Modified After (string) or Modified After (null) (Modified After)
Examples:
  • - Disable modified_after filter
  • modified_after=2023-02-01 - Example to filter assets modified after '2023-02-01'
  • modified_after=2023-07-01 - Example to filter assets modified after '2023-07-01'

Filter results to only include assets modified after a specified date

Modified Before (string) or Modified Before (null) (Modified Before)
Examples:
  • - Disable modified_before filter
  • modified_before=2023-02-01 - Example to filter assets modified before '2023-02-01'
  • modified_before=2023-07-01 - Example to filter assets modified before '2023-07-01'

Filter results to only include assets modified before a specified date

File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than)
Examples:
  • - Disable file size greater than filter
  • file_size_greater_than=5MB - Example to filter files larger than 5MB
  • file_size_greater_than=10MB - Example to filter files larger than 10MB

Filter results to only include files larger than a specific size

File Size Less Than (string) or File Size Less Than (null) (File Size Less Than)
Examples:
  • - Disable file size less than filter
  • file_size_less_than=1GB - Example to filter files smaller than 1GB
  • file_size_less_than=500MB - Example to filter files smaller than 500MB

Filter results to only include files smaller than a specific size

created_by
string (Created By)
Default: ""

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_created_by
string (Exclude Created By)
Default: ""
Examples:
  • exclude_created_by=alex - Example to exclude assets created by 'Alex'
  • exclude_created_by=jordan - Example to exclude assets created by 'Jordan'

Exclude assets created by a specific user from the results

modified_by
string (Modified By)
Default: ""

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

exclude_modified_by
string (Exclude Modified By)
Default: ""
Examples:
  • exclude_modified_by=Chris - Example to exclude assets modified by 'Chris'
  • exclude_modified_by=Pat - Example to exclude assets modified by 'Pat'

Exclude assets modified by a specific user from the results

Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold)
Examples:
  • similarity_threshold=0 - Example similarity threshold set to 0
  • similarity_threshold=0.7 - Example similarity threshold set to 0.7

Set the similarity threshold for embedding-based searches. This functionality allows filtering duplicates and returning only those results that are different from each other. Assets are considered to be duplicates if the cosine distance betwen the embeddings a smaller than the similarity_threshold value, which could be in the [0, 2] range.

Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold)
Examples:
  • - No cutoff threshold (keep every vector hit)
  • cutoff_threshold=1.05 - Drop vector hits with near-zero cosine similarity
  • cutoff_threshold=1.3 - Keep only strongly similar vector hits (cosine >= 0.3)

Minimum raw engine score for vector search legs only, applied per leg before rank fusion. Scale is the engine's transformed score (innerproduct kNN over normalized SigLIP2 maps ip >= 0 to 1 + ip), so the useful range is roughly 1.0-2.0; values below 1.0 are effectively no-ops.

search_path
string (Search Path)
Default: ""
Examples:
  • search_path=/Projects - Example to specify search location under '/Projects'
  • search_path=/Archives/2021 - Example to specify search location in '/Archives/2021'

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

exclude_search_path
string (Exclude Search Path)
Default: ""
Examples:
  • exclude_search_path=/Projects - Example to specify that '/Projects' is excluded
  • exclude_search_path=*/Archives/2021* - Example to specify that any path with this: '*/Archives/2021*' needs to be excluded

Specify the search path within the storage backend. This path should not contain the storage backend URL, just the asset path on the storage backend. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp)
Examples:
  • - Disable URL regex filter
  • filter_url_regexp=.*/Projects/.* - Example to specify that only '/Projects' folder in included in search
  • filter_url_regexp=~(.*/Projects/.*) - Example to specify that any path with this: '/Projects/*' needs to be excluded

Specify an asset URL filter in the Lucene Regexp format.

search_in_scene
string (Search In Scene)
Default: ""
Examples:
  • search_in_scene=s3://bucket-name/Projects/scene1.usd - Example scene URL stored on an S3 bucket
  • search_in_scene=omniverse://example.org/scene2.usd - Example scene URL stored on an Omniverse Nucleus server

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

filter_by_properties
string (Filter By Properties)
Default: ""
Examples:
  • filter_by_properties=color=red,size=S - Example filter by 'color=red' and 'size=S'
  • filter_by_properties=material=plastic,weight=light - Example filter by 'material=plastic' and 'weight=light'

Filter assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456, to search for key only use key=, and to search for value only =value

filter_by_properties_include_any
string (Filter By Properties Include Any)
Default: ""
Examples:
  • filter_by_properties_include_any=color=red,size=S - Example: match assets with color=red OR size=S

Filter assets by USD attributes using OR logic — matches if at least one property condition is satisfied. Same format as filter_by_properties: attribute1=abc,attribute2=456 or attribute1=~*abc*,attribute2=~*456* for wildcards

exclude_filter_by_properties
string (Exclude Filter By Properties)
Default: ""
Examples:
  • exclude_filter_by_properties=color=red,size=S - Example filter to exclude 'color=red' and 'size=S'
  • exclude_filter_by_properties=material=plastic,weight=light - Example filter to exclude 'material=plastic' and 'weight=light'

Exclude assets by USD attributes (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456

filter_by_properties_numeric
string (Filter By Properties Numeric)
Default: ""
Examples:
  • filter_by_properties_numeric=physics:mass>1.0 - Filter by mass > 1.0
  • filter_by_properties_numeric=physics:mass>=1.0,physics:mass<=10.0 - Filter by mass between 1.0 and 10.0
  • filter_by_properties_numeric=physics:density<=500 - Filter by density <= 500

Filter assets by numeric USD attributes with comparison operators. Format: property>value,property<=value. Supported operators: >, >=, <, <=, =. Example: physics:mass>1.0,physics:density<=500

filter_by_tags
string (Filter By Tags)
Default: ""
Examples:
  • filter_by_tags=tag1,tag2,tag3 - Example filter by tags 'tag1,tag2,tag3'

Filter by tags. Format: tag1,tag2,tag3

Min Bbox X (number) or Min Bbox X (null) (Min Bbox X)

Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y)

Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z)

Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox X (number) or Max Bbox X (null) (Max Bbox X)

Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y)

Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z)

Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset

return_images
boolean (Return Images)
Default: false

Return images if set to True

return_metadata
boolean (Return Metadata)
Default: false

Return metadata if set to True

return_root_prims
boolean (Return Root Prims)
Default: false

Return root prims if set to True

return_default_prims
boolean (Return Default Prims)
Default: false

Return default prims if set to True

return_predictions
boolean (Return Predictions)
Deprecated
Default: false

Returns predictions for each asset in the search results from the fixed vocabulary.

NOTE: This functionality is deprecated and setting this parameter will have no effect starting from USD Search version API 1.3. This parameter will be completely removed from the list of input parameters in USD Search API version 2 and above. Please rely on VLM-based auto-captioning functionality instead.

return_in_scene_instances_prims
boolean (Return In Scene Instances Prims)
Default: false

[in-scene search only] Return prims of instances of objects found in the scene

SearchMethod (string) or Embedding Knn Search Method (null) (Embedding Knn Search Method)

Search method, approximate should be faster but is less accurate. Default is exact

limit
integer (Limit) ( 0 .. 10000 ]
Default: 32

Set the maximum number of results to return from the search, default is 32

offset
integer (Offset) >= 0
Default: 0

Number of results to skip. Prefer the cursor below, which pins the ranking so pages do not overlap or skip. Depth depends on the query shape: filter-only is unbounded, a text query is capped by pagination_max_offset, a multi-leg query by the RRF fusion window. Cannot be combined with validate_results=true.

Cursor (string) or Cursor (null) (Cursor)

Opaque cursor from the previous response's X-Next-Cursor header. Takes precedence over offset. The query must stay identical while paging; limit and the return_* flags may change. Cannot be combined with validate_results=true.

Vision Metadata (string) or Vision Metadata (null) (Vision Metadata)

Uses a keyword match query on metadata fields that were generated using Vision Language Models

return_vision_generated_metadata
boolean (Return Vision Generated Metadata)
Default: false

Returns the metadata fields that were generated using Vision Language Models

return_tags
boolean (Return Tags)
Default: false

Return tags for search results

return_inner_hits
boolean (Return Inner Hits)
Default: false

Return inner hits from nested queries for debugging and detailed scoring

validate_results
boolean (Validate Results)
Default: false

Validate results with VLM

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search Post

All supported search parameters are available as body parameters.

Search endpoint enables comprehensive searches across images (e.g., .jpg, .png) and USD-based 3D models within various storage backends (Nucleus, S3, etc.). It enables users to use natural language, image similarity, and precise metadata criteria (file name, type, date, size, creator, etc.) to locate relevant content efficiently. Furthermore, when integrated with the Asset Graph Service, USD Search API extends its capabilities to include searches based on USD properties and spatial dimensions of 3D model bounding boxes, enhancing the ability to find assets that meet specific requirements.

Pagination: pass offset, or better, the previous response's X-Next-Cursor header back as cursor — it pins the ranking so pages do not overlap or skip. Because this endpoint returns a bare JSON array, the pagination state travels in response headers rather than the body: X-Next-Cursor, X-Has-More (true/false) and X-Paginable-Total (the page-count basis). How deep you can go depends on the query shape: filter-only queries are unbounded, a text query is capped by the deployment's pagination_max_offset, and a multi-leg query is capped by the RRF fusion window. validate_results=true is single-page and cannot be combined with offset/cursor. The richer envelope — including why paging stopped — is on POST /v3/deepsearch/search.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
Request Body schema: application/json
required
File Name (string) or File Name (null) (File Name)

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Exclude File Name (string) or Exclude File Name (null) (Exclude File Name)

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Include (string) or File Extension Include (null) (File Extension Include)

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Exclude (string) or File Extension Exclude (null) (File Extension Exclude)

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Created After (string) or Created After (null) (Created After)

Filter results to only include assets created after a specified date

Created Before (string) or Created Before (null) (Created Before)

Filter results to only include assets created before a specified date

Modified After (string) or Modified After (null) (Modified After)

Filter results to only include assets modified after a specified date

Modified Before (string) or Modified Before (null) (Modified Before)

Filter results to only include assets modified before a specified date

File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than)

Filter results to only include files larger than a specific size

File Size Less Than (string) or File Size Less Than (null) (File Size Less Than)

Filter results to only include files smaller than a specific size

Created By (string) or Created By (null) (Created By)

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Created By (string) or Exclude Created By (null) (Exclude Created By)

Exclude assets created by a specific user from the results

Modified By (string) or Modified By (null) (Modified By)

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Modified By (string) or Exclude Modified By (null) (Exclude Modified By)

Exclude assets modified by a specific user from the results

Search Path (string) or Search Path (null) (Search Path)

Limit search to assets within this directory path on the storage backend. Do NOT include the storage backend URL prefix (e.g., use '/Projects/Vehicles/' not 'omniverse://server/Projects/Vehicles/'). Supports wildcards: * for any characters, ? for single character.

Exclude Search Path (string) or Exclude Search Path (null) (Exclude Search Path)

Exclude assets within this directory path. Same format as search_path — do NOT include the storage backend URL prefix. Supports wildcards: * for any characters, ? for single character.

Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp)

Specify an asset URL filter in the Lucene Regexp format.

Search In Scene (string) or Search In Scene (null) (Search In Scene)

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

Filter By Properties (string) or Filter By Properties (null) (Filter By Properties)

Filter assets by USD attributes where at least one root prim matches ALL listed conditions (AND logic). Format: key=value pairs comma-separated. Use =~ prefix on value for wildcard matching. Examples: class=vehicle (exact), class=~*vehicle* (wildcard), class=vehicle,material=metal (both must match). Only a subset of indexed attributes is searchable.

Filter By Properties Include Any (string) or Filter By Properties Include Any (null) (Filter By Properties Include Any)

Filter assets by USD attributes using OR logic — an asset matches if ANY of the listed property conditions match. Same format as filter_by_properties: key=value for exact, key=~*pattern* for wildcard. Example: class=car,class=truck matches assets with either class.

Exclude Filter By Properties (string) or Exclude Filter By Properties (null) (Exclude Filter By Properties)

Exclude assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456 for exact matches or *attribute1*=~*abc*,*attribute2*=~*456* for wildcard matches

Filter By Properties Numeric (string) or Filter By Properties Numeric (null) (Filter By Properties Numeric)

Filter assets by numeric USD attributes with comparison operators. Format: property>value,property<=value. Supported operators: >, >=, <, <=, =. Example: physics:mass>1.0,physics:density<=500

Filter By Tags (string) or Filter By Tags (null) (Filter By Tags)

Filter assets by tags. Format: tag1=,=value2,tag3=value3

Min Bbox X (number) or Min Bbox X (null) (Min Bbox X)

Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y)

Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z)

Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox X (number) or Max Bbox X (null) (Max Bbox X)

Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y)

Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z)

Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset

bbox_use_scaled_dimensions
boolean (Bbox Use Scaled Dimensions)
Default: true

Use scaled dimensions for bounding box filtering

Vision Metadata (string) or Vision Metadata (null) (Vision Metadata)

Uses a keyword match query on metadata fields that were generated using Vision Language Models. Format: attribute1=abc,attribute2=456

Description (string) or Description (null) (Description)

Legacy text search query using AI-powered semantic matching. For new integrations, prefer hybrid_text_query on DeepSearchSearchRequestV2 (POST /search_hybrid) which combines text+vector search for better results.

Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search)

Find visually similar assets by providing reference images. Accepts base64-encoded images (JPEG/PNG/GIF), data URLs (data:image/jpeg;base64,...), or asset URLs (omniverse:// or s3://). Up to 10 images. Can be combined with text search for multimodal queries.

Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold)

Deduplication threshold using embedding cosine distance. Assets with cosine distance below this value are considered duplicates — only the highest-scoring one is returned. Range [0, 2]. Typical values: 0.1 for light dedup, 0.3 for aggressive dedup, None to disable.

Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold)

Minimum raw engine score for VECTOR search legs only (text/keyword legs are never cut off). Applied per leg BEFORE Reciprocal Rank Fusion, so a cut hit can still appear if another leg ranks it. The scale is the engine's transformed score, not plain cosine: for innerproduct kNN over normalized SigLIP2 embeddings OpenSearch maps ip >= 0 to 1 + ip, so the useful range is roughly 1.0 (orthogonal) to 2.0 (identical); values below 1.0 are effectively no-ops. Leave unset to keep every vector hit.

return_images
boolean (Return Images)
Default: false

Return base64-encoded thumbnail images for each result. Recommended: true for visual inspection of search results.

return_metadata
boolean (Return Metadata)
Default: false

Return file metadata (created/modified dates, user, size, etag) for each result

return_root_prims
boolean (Return Root Prims)
Default: false

Return USD root prim data (type, bounding box, properties) for each result. Provides scene structure information.

return_default_prims
boolean (Return Default Prims)
Default: false

Return USD default prim data for each result. The default prim is the entry point when referencing this asset.

return_predictions
boolean (Return Predictions)
Default: false

Return ML model predictions (object classification, segmentation) for each result

return_in_scene_instances_prims
boolean (Return In Scene Instances Prims)
Default: false

[In-scene search only] Return prims of instances of objects found in the scene when using search_in_scene. Only meaningful when search_in_scene is set.

SearchMethod (string) or null

Vector search method: 'exact' (brute-force, more accurate, slower) or 'approximate' (HNSW, faster, may miss some results). Default is exact. Use approximate for large-scale exploratory searches.

limit
integer (Limit) ( 0 .. 10000 ]
Default: 32

Maximum number of results to return (1-10000, default 32). Use 20-50 for initial exploration, 100+ for exhaustive search. Higher limits increase response time.

return_vision_generated_metadata
boolean (Return Vision Generated Metadata)
Default: false

Returns the metadata fields that were generated using Vision Language Models

return_inner_hits
boolean (Return Inner Hits)
Default: false

Return detailed inner hits showing which nested documents matched (e.g., specific embedding offsets or USD property values)

return_tags
boolean (Return Tags)
Default: false

Return asset tags (key-value pairs) in the source data for each result

validate_results
boolean (Validate Results)
Default: false

Validate results with VLM

offset
integer (Offset) >= 0
Default: 0

Number of results to skip — the simple, stateless way to reach page N. Prefer cursor from the previous response: it pins the ranking window so results stay consistent between pages, and it is the only way past OpenSearch's 10000-result window. How deep offset may go depends on the query shape: filter-only queries (no text/image/vector) are unbounded, a text query is capped by the deployment's pagination_max_offset, and a multi-leg (hybrid) query is capped by the RRF fusion window. Cannot be combined with validate_results=true.

Cursor (string) or Cursor (null) (Cursor)

Opaque cursor from the previous response's next_cursor (v3) or X-Next-Cursor header (v2). Takes precedence over offset. The query must stay identical while paging — changing it invalidates the cursor with a 400 rather than silently re-ranking. Page size (limit) and the return_* response flags may change freely mid-walk. Cannot be combined with validate_results=true.

ScoringConfig (object) or null

Advanced scoring configuration controlling how text, vector, and filter results are combined via RRF. Leave as default for standard behavior, or customize field weights and RRF parameters for fine-tuned ranking.

Hybrid Text Query (string) or Hybrid Text Query (null) (Hybrid Text Query)

Natural language search query for text-based search across multiple configurable fields (name, path, properties, AI-generated metadata). Use SHORT descriptive phrases (2-5 words) for best results. Combine with vector_queries using the same text for optimal hybrid search.

Array of objects (Vector Queries)

Vector similarity queries for semantic search. Typically used with same text as hybrid_text_query for hybrid search: [{field_name: 'siglip2-embedding.embedding', query_type: 'text', query: ''}]. Multiple queries search different vector fields in parallel.

return_embeddings
boolean (Return Embeddings)
Default: false

Return raw embedding vectors for search results. Useful for client-side similarity computations or caching.

return_usd_properties
boolean (Return Usd Properties)
Default: false

Return USD attributes (semantic labels, physics properties, etc.) from root prims for each result

return_usd_dimensions
boolean (Return Usd Dimensions)
Default: false

Return bounding box dimensions (bbox_dimension_x/y/z) for each result. Useful for size-based filtering or layout planning.

deduplicate_by_hash
boolean (Deduplicate By Hash)
Default: false

Collapse results with identical content hashes, returning only the highest-scoring version. Useful when the same asset exists at multiple paths.

Responses

Request samples

Content type
application/json
{
  • "file_extension_include": "usd*",
  • "hybrid_text_query": "red car vehicle",
  • "limit": 20,
  • "return_images": true,
  • "return_metadata": true,
  • "title": "Minimal hybrid search (recommended starting point)",
  • "vector_queries": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Stats Usd Properties

Inventory of USD properties across the indexed corpus: every unique property key, every unique value, and every unique key=value pair — each with the number of assets that carry it (asset_count), sorted by coverage. The full lists (not just counts) power property discovery; see the /usd-property-catalog skill, which turns this into a local catalog + filter config.

Filtering. Pass any of the filter parameters that /search accepts (search_path, file_extension_include, filter_by_properties, filter_by_tags, dates, bbox dimensions, search_in_scene, …) to inventory a subset of the corpus instead — "which properties do the assets under /Projects/Vehicles carry?". Passing none inventories everything, as before.

Counts stay exact for whatever subset is selected: this is an aggregation over the whole matching set, not a summary of one page of search results. Filtering is asset-scoped, so filter_by_properties=class=vehicle returns every property those assets carry, not just class — which is what makes drill-down work.

Search-only parameters (description, vector/image queries, limit, offset) are rejected with a 422: an aggregation has no ranking to apply them to, and silently ignoring them would return corpus-wide numbers that look filtered.

Not access-filtered. Results describe the index itself, not the subset of assets the caller could download — with or without filters. Deployments that cannot accept that should turn aggregations off (enable_aggregations=false), which makes this endpoint return 403.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
File Name (string) or File Name (null) (File Name)
Examples: file_name=robot.usd file_name=*scene*

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Exclude File Name (string) or Exclude File Name (null) (Exclude File Name)
Examples: exclude_file_name=draft* exclude_file_name=*temp*

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Include (string) or File Extension Include (null) (File Extension Include)
Examples: file_extension_include=usd file_extension_include=usd* file_extension_include=jpg,png,gif

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Exclude (string) or File Extension Exclude (null) (File Extension Exclude)
Examples: file_extension_exclude=jpg file_extension_exclude=jpg,png,gif file_extension_exclude=mdl

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Created After (string) or Created After (null) (Created After)
Examples: created_after=2023-01-01 created_after=2023-06-01

Filter results to only include assets created after a specified date

Created Before (string) or Created Before (null) (Created Before)
Examples: created_before=2023-01-01 created_before=2023-06-01

Filter results to only include assets created before a specified date

Modified After (string) or Modified After (null) (Modified After)
Examples: modified_after=2023-02-01 modified_after=2023-07-01

Filter results to only include assets modified after a specified date

Modified Before (string) or Modified Before (null) (Modified Before)
Examples: modified_before=2023-02-01 modified_before=2023-07-01

Filter results to only include assets modified before a specified date

File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than)
Examples: file_size_greater_than=1KB file_size_greater_than=10MB

Filter results to only include files larger than a specific size

File Size Less Than (string) or File Size Less Than (null) (File Size Less Than)
Examples: file_size_less_than=100MB file_size_less_than=1GB

Filter results to only include files smaller than a specific size

Created By (string) or Created By (null) (Created By)
Examples: created_by=ov_user

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Created By (string) or Exclude Created By (null) (Exclude Created By)
Examples: exclude_created_by=ov_user

Exclude assets created by a specific user from the results

Modified By (string) or Modified By (null) (Modified By)
Examples: modified_by=ov_user

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Modified By (string) or Exclude Modified By (null) (Exclude Modified By)
Examples: exclude_modified_by=ov_user

Exclude assets modified by a specific user from the results

Search Path (string) or Search Path (null) (Search Path)
Examples: search_path=/Projects/Vehicles/ search_path=/Samples/*

Limit search to assets within this directory path on the storage backend. Do NOT include the storage backend URL prefix (e.g., use '/Projects/Vehicles/' not 'omniverse://server/Projects/Vehicles/'). Supports wildcards: * for any characters, ? for single character.

Exclude Search Path (string) or Exclude Search Path (null) (Exclude Search Path)
Examples: exclude_search_path=/Projects/Archive/ exclude_search_path=*/tmp/*

Exclude assets within this directory path. Same format as search_path — do NOT include the storage backend URL prefix. Supports wildcards: * for any characters, ? for single character.

Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp)
Examples: filter_url_regexp=.*[/]Vehicles[/].* filter_url_regexp=~(.*[/]temp[/].*)

Specify an asset URL filter in the Lucene Regexp format.

Search In Scene (string) or Search In Scene (null) (Search In Scene)
Examples: search_in_scene=s3://bucket-name/Project/scene.usd

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

Filter By Properties (string) or Filter By Properties (null) (Filter By Properties)
Examples: filter_by_properties=class=vehicle filter_by_properties=class=~*vehicle* filter_by_properties=class=vehicle,material=metal

Filter assets by USD attributes where at least one root prim matches ALL listed conditions (AND logic). Format: key=value pairs comma-separated. Use =~ prefix on value for wildcard matching. Examples: class=vehicle (exact), class=~*vehicle* (wildcard), class=vehicle,material=metal (both must match). Only a subset of indexed attributes is searchable.

Filter By Properties Include Any (string) or Filter By Properties Include Any (null) (Filter By Properties Include Any)
Examples: filter_by_properties_include_any=class=car,class=truck

Filter assets by USD attributes using OR logic — an asset matches if ANY of the listed property conditions match. Same format as filter_by_properties: key=value for exact, key=~*pattern* for wildcard. Example: class=car,class=truck matches assets with either class.

Exclude Filter By Properties (string) or Exclude Filter By Properties (null) (Exclude Filter By Properties)
Examples: exclude_filter_by_properties=class=vehicle exclude_filter_by_properties=class=~*draft*

Exclude assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456 for exact matches or *attribute1*=~*abc*,*attribute2*=~*456* for wildcard matches

Filter By Properties Numeric (string) or Filter By Properties Numeric (null) (Filter By Properties Numeric)
Examples: filter_by_properties_numeric=physics:mass>1.0 filter_by_properties_numeric=physics:mass>1.0,physics:density<=500

Filter assets by numeric USD attributes with comparison operators. Format: property>value,property<=value. Supported operators: >, >=, <, <=, =. Example: physics:mass>1.0,physics:density<=500

Filter By Tags (string) or Filter By Tags (null) (Filter By Tags)
Examples: filter_by_tags=reviewed= filter_by_tags==production filter_by_tags=status=approved

Filter assets by tags. Format: tag1=,=value2,tag3=value3

Min Bbox X (number) or Min Bbox X (null) (Min Bbox X)
Examples: min_bbox_x=1

Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y)
Examples: min_bbox_y=1

Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z)
Examples: min_bbox_z=1

Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox X (number) or Max Bbox X (null) (Max Bbox X)
Examples: max_bbox_x=100

Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y)
Examples: max_bbox_y=100

Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z)
Examples: max_bbox_z=100

Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset

bbox_use_scaled_dimensions
boolean (Bbox Use Scaled Dimensions)
Default: true

Use scaled dimensions for bounding box filtering

Vision Metadata (string) or Vision Metadata (null) (Vision Metadata)
Examples: vision_metadata=material=metal vision_metadata=color=red,style=modern

Uses a keyword match query on metadata fields that were generated using Vision Language Models. Format: attribute1=abc,attribute2=456

Responses

Response samples

Content type
application/json
{
  • "unique_keys": [
    ],
  • "unique_values": [
    ],
  • "kv_pairs": [
    ]
}

Hybrid Search Post

Search for 3D assets using combined text + vector + filter search with Reciprocal Rank Fusion scoring.

This is the recommended endpoint for AI agents and programmatic access. It combines:

  • Hybrid Text Search: Keyword matching across asset names, paths, USD properties, and AI-generated metadata
  • Vector Similarity Search: Semantic matching using SigLIP2 vision-language embeddings (1536 dims)
  • Reciprocal Rank Fusion (RRF): Merges text and vector results into a single high-quality ranking
  • Extensive Filtering: File metadata, dates, USD properties, bounding box dimensions, tags
  • VLM Validation: Optional server-side validation of results using a Vision Language Model

Quick Start for AI Agents:

  1. Set hybrid_text_query to a short description (2-5 words)
  2. Add a vector_queries entry with field_name="siglip2-embedding.embedding", query_type="text", same query text
  3. Set file_extension_include="usd*" for USD assets
  4. Set return_images=true for visual inspection
  5. Use limit=20-50 for exploration

Pagination: pass offset, or better, the previous response's next_cursor back as cursor — it pins the ranking so pages do not overlap or skip. The response carries next_cursor, has_more, paginable_total (the page-count basis — not corpus_total) and a pagination diagnostic block whose depth_limit_reason distinguishes "no more results" from "cannot page further for this query shape". Depth depends on the shape: filter-only queries are unbounded, a text query is capped by the deployment's pagination_max_offset, and a multi-leg query is capped by the RRF fusion window. validate_results=true is single-page and cannot be combined with offset/cursor.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
Request Body schema: application/json
required
File Name (string) or File Name (null) (File Name)

Filter results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Exclude File Name (string) or Exclude File Name (null) (Exclude File Name)

Exclude results by asset file name, allowing partial matches. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Include (string) or File Extension Include (null) (File Extension Include)

Filter results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

File Extension Exclude (string) or File Extension Exclude (null) (File Extension Exclude)

Exclude results by file extension. Use wildcards: * for any number of characters, ? for a single character. Separate terms with , for OR and ; for AND.

Created After (string) or Created After (null) (Created After)

Filter results to only include assets created after a specified date

Created Before (string) or Created Before (null) (Created Before)

Filter results to only include assets created before a specified date

Modified After (string) or Modified After (null) (Modified After)

Filter results to only include assets modified after a specified date

Modified Before (string) or Modified Before (null) (Modified Before)

Filter results to only include assets modified before a specified date

File Size Greater Than (string) or File Size Greater Than (null) (File Size Greater Than)

Filter results to only include files larger than a specific size

File Size Less Than (string) or File Size Less Than (null) (File Size Less Than)

Filter results to only include files smaller than a specific size

Created By (string) or Created By (null) (Created By)

Filter results to only include assets created by a specific user. In case AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Created By (string) or Exclude Created By (null) (Exclude Created By)

Exclude assets created by a specific user from the results

Modified By (string) or Modified By (null) (Modified By)

Filter results to only include assets modified by a specific user. In the case, when AWS S3 bucket is used as a storage backend, this field corresponds to the owner's ID. In case of an Omniverse Nucleus server, this field may depend on the configuration, but typically corresponds to user email.

Exclude Modified By (string) or Exclude Modified By (null) (Exclude Modified By)

Exclude assets modified by a specific user from the results

Search Path (string) or Search Path (null) (Search Path)

Limit search to assets within this directory path on the storage backend. Do NOT include the storage backend URL prefix (e.g., use '/Projects/Vehicles/' not 'omniverse://server/Projects/Vehicles/'). Supports wildcards: * for any characters, ? for single character.

Exclude Search Path (string) or Exclude Search Path (null) (Exclude Search Path)

Exclude assets within this directory path. Same format as search_path — do NOT include the storage backend URL prefix. Supports wildcards: * for any characters, ? for single character.

Filter Url Regexp (string) or Filter Url Regexp (null) (Filter Url Regexp)

Specify an asset URL filter in the Lucene Regexp format.

Search In Scene (string) or Search In Scene (null) (Search In Scene)

Conduct the search within a specific scene. Provide the full URL for the asset including the storage backend URL prefix.

Filter By Properties (string) or Filter By Properties (null) (Filter By Properties)

Filter assets by USD attributes where at least one root prim matches ALL listed conditions (AND logic). Format: key=value pairs comma-separated. Use =~ prefix on value for wildcard matching. Examples: class=vehicle (exact), class=~*vehicle* (wildcard), class=vehicle,material=metal (both must match). Only a subset of indexed attributes is searchable.

Filter By Properties Include Any (string) or Filter By Properties Include Any (null) (Filter By Properties Include Any)

Filter assets by USD attributes using OR logic — an asset matches if ANY of the listed property conditions match. Same format as filter_by_properties: key=value for exact, key=~*pattern* for wildcard. Example: class=car,class=truck matches assets with either class.

Exclude Filter By Properties (string) or Exclude Filter By Properties (null) (Exclude Filter By Properties)

Exclude assets by USD attributes where at least one root prim matches (note: only supported for a subset of attributes indexed). Format: attribute1=abc,attribute2=456 for exact matches or *attribute1*=~*abc*,*attribute2*=~*456* for wildcard matches

Filter By Properties Numeric (string) or Filter By Properties Numeric (null) (Filter By Properties Numeric)

Filter assets by numeric USD attributes with comparison operators. Format: property>value,property<=value. Supported operators: >, >=, <, <=, =. Example: physics:mass>1.0,physics:density<=500

Filter By Tags (string) or Filter By Tags (null) (Filter By Tags)

Filter assets by tags. Format: tag1=,=value2,tag3=value3

Min Bbox X (number) or Min Bbox X (null) (Min Bbox X)

Filter by minimum X axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Y (number) or Min Bbox Y (null) (Min Bbox Y)

Filter by minimum Y axis dimension of the asset's bounding box of the default prim of the asset

Min Bbox Z (number) or Min Bbox Z (null) (Min Bbox Z)

Filter by minimum Z axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox X (number) or Max Bbox X (null) (Max Bbox X)

Filter by maximum X axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Y (number) or Max Bbox Y (null) (Max Bbox Y)

Filter by maximum Y axis dimension of the asset's bounding box of the default prim of the asset

Max Bbox Z (number) or Max Bbox Z (null) (Max Bbox Z)

Filter by maximum Z axis dimension of the asset's bounding box of the default prim of the asset

bbox_use_scaled_dimensions
boolean (Bbox Use Scaled Dimensions)
Default: true

Use scaled dimensions for bounding box filtering

Vision Metadata (string) or Vision Metadata (null) (Vision Metadata)

Uses a keyword match query on metadata fields that were generated using Vision Language Models. Format: attribute1=abc,attribute2=456

Description (string) or Description (null) (Description)

Legacy text search query using AI-powered semantic matching. For new integrations, prefer hybrid_text_query on DeepSearchSearchRequestV2 (POST /search_hybrid) which combines text+vector search for better results.

Array of Image Similarity Search (strings) or Image Similarity Search (null) (Image Similarity Search)

Find visually similar assets by providing reference images. Accepts base64-encoded images (JPEG/PNG/GIF), data URLs (data:image/jpeg;base64,...), or asset URLs (omniverse:// or s3://). Up to 10 images. Can be combined with text search for multimodal queries.

Similarity Threshold (number) or Similarity Threshold (null) (Similarity Threshold)

Deduplication threshold using embedding cosine distance. Assets with cosine distance below this value are considered duplicates — only the highest-scoring one is returned. Range [0, 2]. Typical values: 0.1 for light dedup, 0.3 for aggressive dedup, None to disable.

Cutoff Threshold (number) or Cutoff Threshold (null) (Cutoff Threshold)

Minimum raw engine score for VECTOR search legs only (text/keyword legs are never cut off). Applied per leg BEFORE Reciprocal Rank Fusion, so a cut hit can still appear if another leg ranks it. The scale is the engine's transformed score, not plain cosine: for innerproduct kNN over normalized SigLIP2 embeddings OpenSearch maps ip >= 0 to 1 + ip, so the useful range is roughly 1.0 (orthogonal) to 2.0 (identical); values below 1.0 are effectively no-ops. Leave unset to keep every vector hit.

return_images
boolean (Return Images)
Default: false

Return base64-encoded thumbnail images for each result. Recommended: true for visual inspection of search results.

return_metadata
boolean (Return Metadata)
Default: false

Return file metadata (created/modified dates, user, size, etag) for each result

return_root_prims
boolean (Return Root Prims)
Default: false

Return USD root prim data (type, bounding box, properties) for each result. Provides scene structure information.

return_default_prims
boolean (Return Default Prims)
Default: false

Return USD default prim data for each result. The default prim is the entry point when referencing this asset.

return_predictions
boolean (Return Predictions)
Default: false

Return ML model predictions (object classification, segmentation) for each result

return_in_scene_instances_prims
boolean (Return In Scene Instances Prims)
Default: false

[In-scene search only] Return prims of instances of objects found in the scene when using search_in_scene. Only meaningful when search_in_scene is set.

SearchMethod (string) or null

Vector search method: 'exact' (brute-force, more accurate, slower) or 'approximate' (HNSW, faster, may miss some results). Default is exact. Use approximate for large-scale exploratory searches.

limit
integer (Limit) ( 0 .. 10000 ]
Default: 32

Maximum number of results to return (1-10000, default 32). Use 20-50 for initial exploration, 100+ for exhaustive search. Higher limits increase response time.

return_vision_generated_metadata
boolean (Return Vision Generated Metadata)
Default: false

Returns the metadata fields that were generated using Vision Language Models

return_inner_hits
boolean (Return Inner Hits)
Default: false

Return detailed inner hits showing which nested documents matched (e.g., specific embedding offsets or USD property values)

return_tags
boolean (Return Tags)
Default: false

Return asset tags (key-value pairs) in the source data for each result

validate_results
boolean (Validate Results)
Default: false

Validate results with VLM

offset
integer (Offset) >= 0
Default: 0

Number of results to skip — the simple, stateless way to reach page N. Prefer cursor from the previous response: it pins the ranking window so results stay consistent between pages, and it is the only way past OpenSearch's 10000-result window. How deep offset may go depends on the query shape: filter-only queries (no text/image/vector) are unbounded, a text query is capped by the deployment's pagination_max_offset, and a multi-leg (hybrid) query is capped by the RRF fusion window. Cannot be combined with validate_results=true.

Cursor (string) or Cursor (null) (Cursor)

Opaque cursor from the previous response's next_cursor (v3) or X-Next-Cursor header (v2). Takes precedence over offset. The query must stay identical while paging — changing it invalidates the cursor with a 400 rather than silently re-ranking. Page size (limit) and the return_* response flags may change freely mid-walk. Cannot be combined with validate_results=true.

ScoringConfig (object) or null

Advanced scoring configuration controlling how text, vector, and filter results are combined via RRF. Leave as default for standard behavior, or customize field weights and RRF parameters for fine-tuned ranking.

Hybrid Text Query (string) or Hybrid Text Query (null) (Hybrid Text Query)

Natural language search query for text-based search across multiple configurable fields (name, path, properties, AI-generated metadata). Use SHORT descriptive phrases (2-5 words) for best results. Combine with vector_queries using the same text for optimal hybrid search.

Array of objects (Vector Queries)

Vector similarity queries for semantic search. Typically used with same text as hybrid_text_query for hybrid search: [{field_name: 'siglip2-embedding.embedding', query_type: 'text', query: ''}]. Multiple queries search different vector fields in parallel.

return_embeddings
boolean (Return Embeddings)
Default: false

Return raw embedding vectors for search results. Useful for client-side similarity computations or caching.

return_usd_properties
boolean (Return Usd Properties)
Default: false

Return USD attributes (semantic labels, physics properties, etc.) from root prims for each result

return_usd_dimensions
boolean (Return Usd Dimensions)
Default: false

Return bounding box dimensions (bbox_dimension_x/y/z) for each result. Useful for size-based filtering or layout planning.

deduplicate_by_hash
boolean (Deduplicate By Hash)
Default: false

Collapse results with identical content hashes, returning only the highest-scoring version. Useful when the same asset exists at multiple paths.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "Minimal hybrid search (recommended starting point)",
  • "hybrid_text_query": "red car vehicle",
  • "vector_queries": [
    ],
  • "file_extension_include": "usd*",
  • "return_images": true,
  • "return_metadata": true,
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "total": 0,
  • "corpus_total": 0,
  • "paginable_total": 0,
  • "next_cursor": "string",
  • "has_more": false,
  • "pagination": { },
  • "hits": [
    ],
  • "search_metadata": { }
}

Parse a free-text query into structured search parameters

Uses an LLM with constrained (JSON-schema) decoding to turn free-text into a structured intermediate representation, then deterministically maps it onto search request fields. Returns a 503 if the feature is disabled on this server or the LLM call fails.

Request Body schema: application/json
required
query
required
string (Query) non-empty

Raw free-text search text from the search bar.

Responses

Request samples

Content type
application/json
{
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "interpreted_query": {
    },
  • "search_params": { },
  • "dropped_filters": [
    ],
  • "unmapped_constraints": [
    ]
}

List the filters this deployment supports

Returns the configured filter field catalog (from search_fields.yaml): name, value type, valid operators, description, and examples. Lets the UI show users which filters are available and let them add filters without typing a query. Static metadata — works regardless of whether the LLM extractor is enabled.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Relevance verification

VLM-based validation of search results against the original query.

Validate a single search result with VLM

Validates a single asset image against a query using a Vision Language Model. Returns match status, confidence, similarity score, and reasoning.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
Request Body schema: application/json
required
Asset Url (string) or Asset Url (null) (Asset Url)

Asset URL to validate (mutually exclusive with image_key/image_keys)

Image Key (string) or Image Key (null) (Image Key)

Single image key to validate (mutually exclusive with asset_url/image_keys)

Array of Image Keys (strings) or Image Keys (null) (Image Keys)

List of image keys for multiple views of the asset. The deployment's view budget applies (USDSEARCH_VISION_VALIDATION_MAX_IMAGES_PER_VALIDATION); requests exceeding it are rejected with 400. Mutually exclusive with asset_url/image_key.

Array of Images (strings) or Images (null) (Images)

Raw base64-encoded images (data URL or bare base64) to validate directly. When provided, the server validates these images as-is and does NOT fetch anything from the index. Mutually exclusive with asset_url/image_key/image_keys. The deployment view budget (USDSEARCH_VISION_VALIDATION_MAX_IMAGES_PER_VALIDATION) applies.

Query Text (string) or Query Text (null) (Query Text)

Text query to validate against

Query Image (string) or Query Image (null) (Query Image)

Base64 image query to validate against

Responses

Request samples

Content type
application/json
{
  • "asset_url": "string",
  • "image_key": "string",
  • "image_keys": [
    ],
  • "images": [
    ],
  • "query_text": "string",
  • "query_image": "string"
}

Response samples

Content type
application/json
{
  • "is_match": true,
  • "confidence": 0,
  • "similarity_score": 0,
  • "reasoning": "string",
  • "model": "string"
}

Asset

Check asset indexing status per plugin

Check whether a specific asset has been fully indexed by USD Search. Use this to verify if an asset will appear in search results, or to diagnose why it might be missing.

For each URL the service checks caches of all plugins that support processing this asset and reports the following information:

  • indexing_status [not_found / in_sync / out_of_sync ] - this parameter checks the difference between cached value of asset hash and the actual (up-to-date) asset hash from the storage backend.

    • if these two values match - then the asset is considered to be up-to-date, in other words in_sync
    • otherwise, the final version of the asset has not be processed yet.
    • The not_found status is assigned in case the asset has never been processed.

  • plugin_status_history - is a list of last statuses that were assigned to the asset, while it was being processed. Each item of this list has the following structure:

    • status [ok / processing / failed_retries_exhausted / other string] - shows whether the asset was

      • ok - successfully processed
      • processing - processing for the asset has started
      • failed_retries_exhausted - processing of the asset failed and reached the retry limit
      • any other string - indicates that that processing has failed with this message.

    • processing_timestamp - the moment when the status was assigned

    • exception - optional exception explanation

The service could additionally report asset metadata from the storage backend if return_asset_metadata flag is set to True.

query Parameters
url
required
string (Url)

Asset URL for which processing status needs to be retrieved

return_asset_metadata
boolean (Return Asset Metadata)
Default: false

Return metadata for the asset if set to True

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "plugins_statuses": {
    },
  • "storage_backend_info": {
    }
}

On-demand asset processing

USD Search processes all assets on the storage backend in the background. This, however, may take time depending on the amount of data on the storage backend and the amount of available resources, which could lead to delays in specific assets appearing in the search index. In order to address this and prioritize processing of specific assets, it is possible to use this endpoint to trigger indexing of a specific asset on demand.

When triggering processing of a specific asset URL the user could decide, with which plugin the asset needs to be processed. By default, when no plugin is selected - the service will trigger processing for all plugins that could work with this asset type. Please find below the list of supported plugins:

  • asset_graph_generation: Constructs several graphs based on the prim hierarchy of a USD file. This plugin is an essential component of Asset Graph Service (AGS).

    • This plugin supports the following data types: usdz, usdc, usd, usda

  • image_to_embedding: Extracts CLIP embeddings from the images that are found on the storage backend.

    • This plugin supports the following data types: apng, png, dib, msp, xpm, avif, vst, bmp, flc, rgba, fit, ftu, sgi, ps, j2k, vda, hdf, ras, jp2, tif, psd, dcx, dds, jpeg, pbm, jpe, bw, blp, jpc, grib, icb, h5, bufr, pfm, qoi, tga, cur, jpg, ftc, fits, gbr, pgm, emf, j2c, fli, exr, iim, webp, jpx, avifs, icns, gif, mpeg, xbm, jfif, eps, pcd, pnm, jpf, im, mpg, rgb, ico, ppm, wmf, pxr, pcx, tiff

  • image_to_vision_metadata: Extracts VLM-generated metadata from the images that are found on the storage backend.

    • This plugin supports the following data types: apng, png, dib, msp, xpm, avif, vst, bmp, flc, rgba, fit, ftu, sgi, ps, j2k, vda, hdf, ras, jp2, tif, psd, dcx, dds, jpeg, pbm, jpe, bw, blp, jpc, grib, icb, h5, bufr, pfm, qoi, tga, cur, jpg, ftc, fits, gbr, pgm, emf, j2c, fli, exr, iim, webp, jpx, avifs, icns, gif, mpeg, xbm, jfif, eps, pcd, pnm, jpf, im, mpg, rgb, ico, ppm, wmf, pxr, pcx, tiff

  • rendering_to_embedding: Renders the asset and extracts CLIP embeddings from the generated preview images.

    • This plugin supports the following data types: usdz, usdc, usd, usda

  • rendering_to_vision_metadata: Renders the asset and extracts VLM-generated metadata using the generated preview images.

    • This plugin supports the following data types: usdz, usdc, usd, usda

  • thumbnail_generation: Renders the asset uploads one of the rendered images to the storage backend to serve as a thumbnail for this asset.

    • This plugin supports the following data types: usdz, usdc, usd, usda

  • thumbnail_to_embedding: For any asset stored on the storage backend this plugin relies on the thumbnail of this asset to extract CLIP embeddings.

    • This plugin supports the following data types: any

  • thumbnail_to_vision_metadata: For any asset stored on the storage backend this plugin relies on the thumbnail of this asset to extract VLM-generated metadata.

    • This plugin supports the following data types: any

NOTE: If some of the plugins are not enabled for the USD Search instance, selecting them for the plugins parameter setting will have not effect. Please reach out to your USD Search service administrator if you would like to enable certain plugin functionality. The list of plugins that are enabled for this USD Search instance could be retrieved using /info/plugins endpoint.

query Parameters
url
required
string (Url)

Asset URL which should be submitted for priority processing

Array of Plugins (strings) or Plugins (null) (Plugins)

List of plugins for which indexing needs to be re-done

refresh_plugins
boolean (Refresh Plugins)
Default: true

re-enqueue plugin processing

refresh_metadata
boolean (Refresh Metadata)
Default: false

refresh asset metadata

refresh_tags
boolean (Refresh Tags)
Default: false

refresh asset tags

JobItemType (string) or Priority (null) (Priority)
Default: "priority"

processing job type

Responses

Response samples

Content type
application/json
null

Storage Backend

Get Storage Backend Info

Display some information about the storage backend(s), to which the USD Search API instance is connected to.

A single Storage API deployment can serve several buckets / namespace roots. These are discovered via ListTopLevelAddresses and reported as one entry per root; backends that expose a single root (or a Storage API server without discovery support) report their configured base_uri.

query Parameters
check_availability
boolean (Check Availability)
Default: false

Check if storage backend is available

Responses

Response samples

Content type
application/json
{
  • "backends": {
    }
}

Plugins

List of supported plugins

Get the list of plugins that are supported by the USD Search instance

query Parameters
only_active
boolean (Only Active)
Default: true

show only active plugins

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Images

Fetch asset thumbnail image — use after search to visually inspect results

Fetch image binary data for a specific asset. This is the primary way to get thumbnails for visual inspection of search results. After running a search query, call this endpoint for each result's source.url (or source.base_key) to get its thumbnail. Use img_offset=0,1,2... to get multiple views/angles of the same asset when available.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
Asset Url (string) or Asset Url (null) (Asset Url)

The complete URL of the asset to fetch image data for. Must be a valid asset URL that the user has access to.

Image Key (string) or Image Key (null) (Image Key)

Direct image key/ID to fetch from OpenSearch. Use this for direct image retrieval when you already know the image identifier.

img_offset
integer (Img Offset) >= 0
Default: 0

Zero-based index specifying which image to fetch from the asset's siglip2-embeddings. Only valid when using asset_url.

Responses

Response samples

Content type
Binary JPEG image data

Download

Download an asset and its dependencies as a ZIP archive

Fetch a USD asset together with all of its transitive dependency files (sublayers, referenced USDs, textures) and return them as a single ZIP. Files are laid out relative to a shared root directory so the scene's relative references resolve after extraction. A manifest.json describing the bundle (root url, included files, any per-file errors) is added at the archive root. Works for every storage backend (S3, Nucleus, local-fs). If the asset has no recorded dependencies (or the asset graph is unavailable) a single-file archive is returned.

Authorizations:
HTTPBearerHTTPBasicAPIKeyHeader
query Parameters
asset_url
required
string (Asset Url)

The complete storage URL of the asset to download (e.g. s3://bucket/path/scene.usd).

manifest_only
boolean (Manifest Only)
Default: false

If true, do not build the ZIP — return JSON describing the bundle (root url, file count, total size in bytes, per-file sizes, errors). Lets a UI show the bundle size before the user commits to the download.

Responses

Response samples

Content type
application/json
{
  • "detail": "Access denied"
}

Metrics

Endpoint that serves Prometheus metrics.

Responses

Response samples

Content type
application/json
null