vaults/{vaultId}/item-versions/{id}/bill-of-materials
Retrieves the bill of materials (BOM) for the specified item version. The snapshot returned depends on the option[bomType] and option[date] query parameters.
Resource Information
| Method and URI | GET /AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/item-versions/{id}/bill-of-materials |
| Authentication Context | User context required |
| Required OAuth Scopes | No scopes required |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.
The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context. |
Request
URI Parameters
| vaultId string | The unique identifier of a Knowledge Vault. |
| id string | The unique identifier of an item version. |
Request
Query String Parameters
| option[bomType] enum:string | The type of BOM snapshot to return. Possible values:
|
| option[date] string | The effective date used when option[bomType] is Effective. Defaults to DateTime.MinValue. |
| option[rolledUp] boolean | true: Include a linear view of the BOM, BOM items for parts only. Only available for view operations.
|
| option[oneLevel] boolean | true: Include only the current level and immediate children.
|
| option[referenceDesignators] boolean | true: Include reference designators.
|
| option[occurrences] boolean | true: Include the occurrences.
|
| option[excludedBOMLinks] boolean | true: Include excluded BOM rows.
|
| option[unassignedComponents] boolean | true: Include unassigned components (BOM rows without associated items) in BOM rows.
|
| option[includeBOMAssociationProperty] boolean | true: Include properties on BOM associations.
|
Response
HTTP Status Code Summary
| 200 OK | The bill of materials links and revisions were successfully retrieved. |
| 400 Bad Request | The server was unable to process the request. The syntax of the request is malformed or the request is missing a required header. Do not repeat the request without fixing the issue. The response body may indicate what is wrong with the request. |
| 401 Unauthorized | The supplied authorization header was not valid or the supplied token scope was not acceptable. Verify authentication and try again. |
| 403 Forbidden | The request was successfully validated but lacking the required permissions. Verify your credentials and permissions before you send this request again. |
Response
Body Structure (200)
| itemVersions array: object | An array of item versions referenced by this BOM structure. |
| id string | The unique identifier (iteration ID) of the item version. |
| url string | The relative URL to access this object. |
| number string | The Item number. |
| version number | The version number, which is a sequential number given to each version. For example, if this value is 5, then the object is the 5th version. |
| revision string | The display value for the revision. |
| comment string | The comment associated with this item version. |
| title string | The display title. |
| state string | The lifecycle state of this item version. |
| stateColor number | The color associated with the item’s lifecycle state. |
| name string | The display name of the item. |
| category string | The category assigned to this item. |
| categoryColor number | The color associated with the item’s category. |
| entityType string | The type of entity represented by this item version. |
| isReadOnly boolean | Indicates whether this item version is read-only for the current user.
|
| isCloaked boolean | Indicates whether this item version is cloaked for the logged-in user.
|
| isLatestObsolete boolean | Indicates whether the latest item version is obsolete.
|
| item object | Contains the item identity and referenced item iteration returned by list operations. |
| id string | The unique identifier (master ID) of the item. |
| url string | The relative URL to access this object. |
| versionType enum:string | Specifies which file or item iteration to resolve. Possible values:
|
| itemVersion object | The referenced item version details. |
| lifecycleState object | Contains a lifecycle state. |
| id string | The unique identifier of a server-based lifecycle state. |
| url string | The relative URL to access this object. |
| name string | The name of this lifecycle state. |
| displayName string | The display name of this lifecycle state. |
| description string | The description of this lifecycle state. |
| comments array: string | A list of predefined comments available for selection when changing entity states. |
| isDefault boolean | true: This state is the default state of the lifecycle definition.
|
| color int | The color code of this lifecycle state icon. |
| isReleasedState boolean | Indicates whether this state is a released state.
|
| isObsoleteState boolean | Indicates whether this state is an obsolete state.
|
| displayOrder int | The display order of this state among other states of the same lifecycle definition. |
| properties array: object | An array of property values for this item version. |
| propertyDefinitionId string | The unique identifier of the property definition that this value belongs to. |
| definition object | Contains server-side metadata for a Vault property definition, including datatype and naming. |
| id string | The unique identifier of the property definition. |
| url string | The relative URL to access this object. |
| displayName string | The display name of this property definition. |
| systemName string | The system name of this property definition. |
| dataType enum:string | The underlying data type stored for values of this property.
Possible values: String, Numeric, Bool, DateTime, Image |
| active boolean | Indicates whether this property definition is active.
|
| isSystem boolean | Indicates whether this property definition is a built-in system property.
|
| initialValue string | The default value applied to entities that do not have an existing value for this property definition. |
| value string | The property value associated with the entity for the referenced property definition. |
| itemBomLinks array: object | An array of BOM links describing the parent-child relationships between items. |
| bomComponentId string | The unique identifier of the BOM component. This value is only valid when the BOM row is a component (not assigned to an item). |
| groupedRow boolean | Indicates whether this BOM association is a grouped row of multiple BOM rows.
|
| groupId string | The unique identifier of the multiple-row grouping. |
| unitSize string | The unit size for this BOM row. |
| instCount string | The instance count of this BOM association. |
| cad boolean | Indicates whether this BOM row is created and maintained by CAD data or is a manual BOM row.
|
| included boolean | Indicates whether this BOM row is included in the BOM.
|
| refDesId string | The reference designator ID. This value will be 0 if reference designators are not available. |
| childHasChildren boolean | Indicates whether the child item has children of its own.
|
| bomLinkMasterId string | The master ID of the item association. This value does not change between iterations. |
| bomOrder string | The order that the child entry shows up in the BOM. |
| units string | The display name for the Unit of Measure on CldItemUsage. |
| quantity string | The quantity for this BOM row. |
| childItemId string | The ID of the child Item. |
| parentItemId string | The ID of the parent Item. |
| id string | The unique identifier of the BOM link. |
| parentMasterChildMasterAndRefDesMaster string | Composite key containing parent master ID, child master ID, and reference designator master ID. |
| childMasterAndRefDesMaster string | Composite key containing child master ID and reference designator master ID. |
| isStatic boolean | Indicates whether the dependency is static or computed.
|
| positionNumber string | The assigned position number for this BOM row. |
| properties array: object | An array of property values for this BOM link. |
| propertyDefinitionId string | The unique identifier of the property definition that this value belongs to. |
| definition object | Contains server-side metadata for a Vault property definition, including datatype and naming. |
| id string | The unique identifier of the property definition. |
| url string | The relative URL to access this object. |
| displayName string | The display name of this property definition. |
| systemName string | The system name of this property definition. |
| dataType enum:string | The underlying data type stored for values of this property.
Possible values: String, Numeric, Bool, DateTime, Image |
| active boolean | Indicates whether this property definition is active.
|
| isSystem boolean | Indicates whether this property definition is a built-in system property.
|
| initialValue string | The default value applied to entities that do not have an existing value for this property definition. |
| value string | The property value associated with the entity for the referenced property definition. |
| referenceDesignatorsAvailable boolean | Indicates whether reference designators are available.
|
| occurrences array: object | An array of occurrences. |
| rootItemId string | The top most Item of the BOM. |
| id string | A unique identifier for this occurrence within the Item BOM. |
| parentOccurrenceId string | The immediate parent. -1 means no parent occurrence. |
| bomLinkMasterId string | The master identifier of the BOM link associated with this occurrence. |
| position string | The position on the BOM. |
| detailId string | The value of the occurrence, also known as the detail ID. |
| path string | The path to the occurrence in the BOM. The format is the list of Item Master IDs separated by the ‘/’ delimiter. |
| bOMComponents array: object | An array of BOM components in this BOM. |
| isCloaked boolean | Indicates whether this BOM component is cloaked.
|
| bOMStructure int | An enumerated value representing the BOM structure of a component. Possible values:
|
| baseQty string | The numeric quantity of a single instance of the component.
For components with discrete quantities, use |
| baseUOM string | The unit of measure used to quantify this component.
For discrete quantities, use |
| componentType int | Specifies the CAD or business role of the BOM component. Possible values:
|
| name string | The name of this component. |
| xRefType enum:string | Specifies whether a component reference is internal or external to the host design file. Possible values:
|
| uniqueId string | The unique identifier of the component within the scope of its design file.
For Inventor files, this is the GUID used to identify the component (or the GUID plus |
| id string | The unique identifier of this BOM component. |
| xRefId string | For Components with a XRefType of “external”, XRefID represents the FileID of the design file associated with that component. For “internal” Components, XRefID should be set to -1. |
Example
This example illustrates how to get BOM for a specific item version.
Note: {VaultServerAddress} is used as a placeholder in the example(s) and could represent one of the following:
- Vault Server IP address or hostname. Ex: http://10.41.110.49.
- Vault Gateway URL if gateway is configured. Ex: https://test.vg.autodesk.com.
Request
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/117/item-versions/57/bill-of-materials' \
-X 'GET' \
-H 'Accept: application/json'\
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a...'
Response
{
"itemVersions": [
{
"name": "Assembly1",
"id": "57",
"revision": "A",
"lastModifiedUserName": "TestAccount",
"lastModifiedDate": "2024-10-22T08:21:31.65Z",
"number": "Assembly1",
"title": "Assembly1",
"description": "",
"comment": "",
"state": "Work in Progress",
"stateColor": -12859030,
"category": "Assembly",
"categoryColor": -10188850,
"isReadOnly": false,
"isCloaked": false,
"isLatestObsolete": false,
"item": {
"id": "55",
"entityType": "Item",
"url": "/AutodeskDM/Services/api/vault/v2/vaults/117/items/55"
},
"version": 2,
"entityType": "ItemVersion",
"url": "/AutodeskDM/Services/api/vault/v2/vaults/117/item-versions/57"
}
],
"itemBomLinks": [],
"referenceDesignatorsAvailable": false,
"occurrences": [],
"bomComponents": []
}