Filter Collection Endpoints
This document provides a comprehensive overview of the various filtering options available for certain endpoints. By utilizing these filters, users can refine their data retrieval processes, ensuring that the results are relevant and tailored to specific needs. The document outlines different types of filters, including query parameters, boolean flags, field-specific filters, and more, along with examples and explanations for each.
1. Query Parameters with Arbitrary Text
These parameters accept arbitrary text, which can be used to search or filter data.
q
Description: The value to use for the search. Based on
option[searchContent]
, this parameter will either search across all properties or across all properties and content.Example:
q=Assembly
- All objects that contain ‘Assembly’ within their properties will be returned.Reference: Searching Vault
2. Query Parameters with Predefined Enums
These parameters accept one of the predefined enumerator values. This is useful for filtering data based on specific categories or states.
option[revision]
Allowed Values:
AllRevision
,CurrentRevision
Default Value:
AllRevision
Example:
option[revision]=CurrentRevision
option[history]
Allowed Values:
All
,ReleasedOnly
,ReleasedAndRevisionTip
,RevisionTip
Default Value:
All
Example:
option[history]=ReleasedOnly
filter[association]
Allowed Values:
User
,Group
,All
Example:
filter[association]=User
filter[entityClassId]
Allowed Values:
FILE
,FLDR
,ITEM
,CO
Example:
filter[entityClassId]=FILE
Note: If null or empty, it will return property definitions for all Entity Classes.
3. Query Parameters with Boolean Flags
These parameters apply predefined filters based on boolean flag values (true
or false
). They are used to include or exclude specific data sets based on the flag’s value.
option[latestOnly]
Default Value:
true
Example:
option[latestOnly]=false
- Include all versions.option[releasedOnly]
Default Value:
false
Example:
option[releasedOnly]=true
- Include only associated files/items that are in the consumable (released) state.option[includeHidden]
Default Value:
false
Example:
option[includeHidden]=true
- Include files marked as hidden.- Other Boolean Flags
option[releaseBiased]
: Use “Release biased” approach of gathering dependencies.option[recurse]
: Include all levels of child/parents.option[includeClosedECOs]
: Include change orders with closed or cancelled state.option[onlyShowTipReleasedForEachRev]
: Only show the tip released version for each revision.option[searchContent]
: Search full content of the file.option[searchSubFolders]
: Search query text within all subfolders.option[includeFolders]
: Include folders or folder links in the search result.option[includeItemEcoLinks]
: Include Item/Change-order Link in the search result.option[includeBOMAssociationProperty]
: Include properties on BOM associations.filter[openCOsOnly]
: Include only open change orders.
4. Query Parameters for Field-Specific Filters
These parameters specify the field on which the filter should be applied. This allows for detailed and precise filtering based on specific attributes of the data. filter[<systemName of the property definition>]
Description: Filters the results based on the system name of the property definition.
Example:
filter[Name]=Assembly
’
- Examples
filter[State]=Open
orfilter[State]=Review
filter[CheckoutUserName]=userA
filter[CreateUserName]=userA
filter[CreateUserName]=Office
- Notes
systemName
is case insensitive.- Avoid adding multiple filters with the same
systemName
. These filters will perform a logical AND operation, potentially resulting in zero results.
5. Path Parameters for Resource Subset Filtering
These parameters filter a subset of resources based on the specified path. This method is useful for narrowing down data to specific segments within a larger collection.
- Example
/folders/{folderId}/contents
6. Additional Endpoint-Specific Filters
This provides a highly customizable filtering mechanism that can cater to complex filtering requirements.
- Query Parameters
filter[systemNames]
Description: Search filter to include only property definitions that match
SystemName
.SystemNames
should be separated by commas.Example:
filter[systemNames]=Name,Description
filter[name]-starts
Description: Filters and returns items whose names start with the specified string.
Example:
filter[name]-starts=Proj
filter[assignees]
Description: Search filter to include only change orders that assignees user list can perform.
Example:
filter[assignees]=1,2,3,4
- Body Parameters
{ "entityTypesToSearch": [ "Folder", "File" ], "searchCriterias": [ { "propertyDefinitionUrl": "/AutodeskDM/Services/api/vault/v2/vaults/1/property-definitions/112", "operator": "IsExactly", "searchString": "true" }, { "propertyDefinitionUrl": "/AutodeskDM/Services/api/vault/v2/vaults/1/property-definitions/123", "operator": "IsExactly", "searchString": "true" }, { "propertyDefinitionUrl": "/AutodeskDM/Services/api/vault/v2/vaults/1/property-definitions/55", "operator": "NotEqualTo", "searchString": "None" } ], "sortCriterias": [ { "propertyDefinitionUrl": "/AutodeskDM/Services/api/vault/v2/vaults/1/property-definitions/27", "ascending": true } ] }
Show More
Explanation of Request Body Fields
- ``entityTypesToSearch``: Specifies the types of entities to be searched (e.g., Folder, File).
- ``searchCriterias``: A list of criteria used to filter the search results. Each criterion includes:
-
propertyDefinitionUrl
: The URL of the property definition. -operator
: The operator used for comparison (e.g., IsExactly, NotEqualTo). -searchString
: The value to compare against. - ``sortCriterias``: A list of criteria used to sort the search results. Each criterion includes:
-
propertyDefinitionUrl
: The URL of the property definition used for sorting. -ascending
: A boolean indicating whether to sort in ascending order.
Use these filtering options to refine responses based on your specific needs, ensuring that you retrieve the most relevant and accurate data.
Method | Description | Filter/Option |
---|---|---|
Options | ||
GET |
Get system options | filter[name] |
GET |
Get all Vault options | filter[name]-starts |
Property | ||
GET |
Get all property definitions | option[includeBOMAssociationProperty] filter[entityClassId] filter[systemNames] filter[propDefIds] |
Files and Folders | ||
GET |
Get folder contents | q option[searchContent] option[searchSubFolders] option[includeFolders] option[includeItemEcoLinks] option[releasedFilesOnly] option[releasedItemsOnly] option[latestOnly] filter[<systemName of the property definition>] |
GET |
Get file versions | q option[releasedFilesOnly] option[latestOnly] filter[<systemName of the property definition>] |
GET |
Get file versions history | option[history] option[onlyShowTipReleasedForEachRev] option[revision] |
GET |
Get file version child associations | option[includeHidden] option[releasedOnly] option[getLatestAssocs] option[recurse] |
GET |
Get file version parent associations | option[includeHidden] option[releasedOnly] option[getLatestAssocs] option[recurse] |
GET |
Get items for file version | option[releasedOnly] |
GET |
Get file Change Orders | option[includeClosedECOs] |
Items | ||
GET |
Get item versions | q option[releasedItemsOnly] option[latestOnly] filter[<systemName of the property definition>] |
GET |
Get item version history | option[history] |
GET |
Get item Change Orders | option[includeClosedECOs] |
Change Orders | ||
GET |
Get all change orders | q filter[assignees] filter[openCOsOnly] filter[<systemName of the property definition>] |
GET |
Get change order files | option[releasedOnly] |
GET |
Get change order comment attachments | option[releasedOnly] |
GET |
Get change order associated entities | option[releasedItemsOnly] option[releasedFilesOnly] |
Search | ||
GET |
Basic search | q option[searchContent] option[searchSubFolders] option[releasedFilesOnly] option[releasedItemsOnly] option[latestOnly] filter[<systemName of the property definition>] |
POST |
Advanced search | option[searchSubFolders] option[releasedFilesOnly] option[releasedItemsOnly] option[latestOnly] |