vaults/{vaultId}/items
Creates and commits a new item using either an explicit item number or an item numbering scheme. Pass exactly one of itemNumber or numberingSchemeUrl. For numbering schemes that include free-text or predefined-list fields, pass the user-entered values in numberingSchemeFieldInputs in scheme field order.
Resource Information
| Method and URI | POST /AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/items |
| 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. |
| Content-Type* string | Must be application/json |
Request
URI Parameters
| vaultId string | The unique identifier of a Knowledge Vault. |
Request
Body Structure
| categoryUrl* string | The relative URL of the item category to assign to the new item. |
| itemNumber string | The explicit item number to assign to the new item. Pass this instead of numberingSchemeUrl when the number is supplied by the caller.
Max length: 128 |
| numberingSchemeUrl string | The relative URL of the item numbering scheme to use when creating the new item number. Pass this instead of itemNumber when the number should be generated from a numbering scheme. |
| numberingSchemeFieldInputs array: string | User-entered values for numbering scheme fields that require input, such as free-text and predefined-list fields. Values must be supplied in the same order as those input fields appear in the numbering scheme. Omit or pass an empty array for fully automatic numbering schemes. |
| unitUrl string | The relative URL of the unit of measure for the new item. If omitted, the item category default is used. |
| title string | The item title. |
| description string | The item description/detail text. |
| comment string | The item commit comment. |
| properties array: object | Initial item property values to set during create. These values are written in the same atomic create transaction as the item commit. |
| propertyDefinitionUrl* string | The relative URL of the property definition that this value belongs to. |
| value string | The property value to set. |
Response
HTTP Status Code Summary
| 201 Created | The item was successfully created. |
| 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. |
| 409 Conflict | The request conflicts with the current Vault state, such as an item number that is already in use. |
Response
Header (201)
| Location string | The URL of the created item. |
Response
Body Structure (201)
| 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 | Contains metadata for an item iteration, including numbering, lifecycle, and referenced item master. |
| 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 | The item master associated with this item version. |
| 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. |
Example
This example illustrates how to create an item using a numbering scheme.
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/9/items' \
-X 'POST' \
-H 'Content-Type: application/json'\
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a...'\
-d '{
"categoryUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/categories/8",
"numberingSchemeUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/numbering-schemes/3",
"numberingSchemeFieldInputs": ["BRK-"],
"title": "Bracket",
"description": "Synced from Fusion Manage",
"comment": "created via REST",
"unitUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/units-of-measure/1",
"properties": [
{
"propertyDefinitionUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/property-definitions/109",
"value": "Steel"
}
]
}'
On success, Vault returns 201 Created. The response includes a Location header with the URL of the new item. The JSON body below shows the created item and its initial item version.
Response
{
"id": "217",
"itemVersion": {
"name": "BRK-000123",
"id": "218",
"number": "BRK-000123",
"title": "Bracket",
"description": "Synced from Fusion Manage",
"comment": "created via REST",
"state": "Work in Progress",
"category": "Part",
"item": {
"id": "217",
"entityType": "Item",
"url": "/AutodeskDM/Services/api/vault/v2/vaults/9/items/217"
},
"url": "/AutodeskDM/Services/api/vault/v2/vaults/9/item-versions/218"
},
"url": "/AutodeskDM/Services/api/vault/v2/vaults/9/items/217"
}