vaults/{vaultId}/folders:update-states
Updates lifecycle states for multiple folders by master IDs.
Resource Information
| Method and URI | POST /AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/folders:update-states |
| 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
| updateLifecycleStateRequests* array: object | An array of requests to update the lifecycle state of entities (at least one entry required). |
| entityUrl* string | The URL of the entity to update. For files and items, use the File or Item entity type rather than the FileVersion or ItemVersion entity type. |
| lifecycleStateUrl* string | The URL of the target lifecycle state. |
| revision string | An optional revision label to apply during the state transition. Applicable to files and items only; omit for folders or when the revision should be determined by lifecycle rules. |
| comment string | A comment to be added when changing the lifecycle state. |
Response
HTTP Status Code Summary
| 200 OK | The folder lifecycle states were successfully updated. |
| 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. |
| 404 Not Found | The requested resource was not found. |
Response
Body Structure (200)
| results array | An array of folders. |
| oneOf array:oneOf | |
| Folder object | Contains standard folder metadata returned by Vault. |
| id string | The unique identifier of this folder. |
| url string | The relative URL to access this object. |
| name string | The descriptive name of this folder. This is the folder name without the full path. |
| fullName string | The full Vault path for this folder (for example, $/Folder1). |
| createDate datetime: ISO 8601 | The date and time when the folder was created. |
| createUserName string | The name of the user who created this folder. |
| category string | The category assigned to this folder. |
| categoryColor number | The color of the category. |
| state string | The name of the lifecycle state for this folder. |
| stateColor number | The color of the lifecycle state. |
| subfolderCount number | The number of immediate child folders. |
| children string | The URI to retrieve child folders. |
| isLibrary boolean | Indicates whether this folder is a library folder.
|
| isReadOnly boolean | Indicates whether this folder can be modified by the logged-in user.
|
| isCloaked boolean | Indicates whether this folder is cloaked. A cloaked object is one that the caller does not have permissions to view.
|
| properties array: object | An array of property values for this folder. |
| 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. |
| Folder object | Contains standard folder metadata returned by Vault. |
| parentFolderId string | The unique identifier of the parent folder. |
| parent all of | The parent folder of this folder. |
| Folder object | Contains standard folder metadata returned by Vault. |
| id string | The unique identifier of this folder. |
| url all of | The relative URL to access this folder. |
| 0 string | The relative URL to access this object. |
| name string | The descriptive name of this folder. This is the folder name without the full path. |
| fullName string | The full Vault path for this folder (for example, $/Folder1). |
| createDate datetime: ISO 8601 | The date and time when the folder was created. |
| createUserName string | The name of the user who created this folder. |
| category string | The category assigned to this folder. |
| categoryColor number | The color of the category. |
| state string | The name of the lifecycle state for this folder. |
| stateColor number | The color of the lifecycle state. |
| subfolderCount number | The number of immediate child folders. |
| children string | The URI to retrieve child folders. |
| isLibrary boolean | Indicates whether this folder is a library folder.
|
| isReadOnly boolean | Indicates whether this folder can be modified by the logged-in user.
|
| isCloaked boolean | Indicates whether this folder is cloaked. A cloaked object is one that the caller does not have permissions to view.
|
| properties array: object | An array of property values for this folder. |
| propertyDefinitionId string | The unique identifier of the property definition that this value belongs to. |
| definition all of | The property definition metadata for this property value. |
| Property 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 all of | The relative URL to access this property definition. |
| 0 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. |
| lifecycleState all of | The lifecycle state of this folder. |
| Lifecycle State object | Contains a lifecycle state. |
| id string | The unique identifier of a server-based lifecycle state. |
| url all of | The relative URL to access this lifecycle state. |
| 0 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. |
| id string | The unique identifier of this folder. |
| url string | The relative URL to access this object. |
| name string | The descriptive name of this folder. This is the folder name without the full path. |
| fullName string | The full Vault path for this folder (for example, $/Folder1). |
| createDate datetime: ISO 8601 | The date and time when the folder was created. |
| createUserName string | The name of the user who created this folder. |
| category string | The category assigned to this folder. |
| categoryColor number | The color of the category. |
| state string | The name of the lifecycle state for this folder. |
| stateColor number | The color of the lifecycle state. |
| subfolderCount number | The number of immediate child folders. |
| children string | The URI to retrieve child folders. |
| isLibrary boolean | Indicates whether this folder is a library folder.
|
| isReadOnly boolean | Indicates whether this folder can be modified by the logged-in user.
|
| isCloaked boolean | Indicates whether this folder is cloaked. A cloaked object is one that the caller does not have permissions to view.
|
| properties array: object | An array of property values for this folder. |
| 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. |
| included object | Contains additional resources included with the folder results. |
| folder object | |
| * object | Contains standard folder metadata returned by Vault. |
| id string | The unique identifier of this folder. |
| url all of | The relative URL to access this folder. |
| 0 string | The relative URL to access this object. |
| name string | The descriptive name of this folder. This is the folder name without the full path. |
| fullName string | The full Vault path for this folder (for example, $/Folder1). |
| createDate datetime: ISO 8601 | The date and time when the folder was created. |
| createUserName string | The name of the user who created this folder. |
| category string | The category assigned to this folder. |
| categoryColor number | The color of the category. |
| state string | The name of the lifecycle state for this folder. |
| stateColor number | The color of the lifecycle state. |
| subfolderCount number | The number of immediate child folders. |
| children string | The URI to retrieve child folders. |
| isLibrary boolean | Indicates whether this folder is a library folder.
|
| isReadOnly boolean | Indicates whether this folder can be modified by the logged-in user.
|
| isCloaked boolean | Indicates whether this folder is cloaked. A cloaked object is one that the caller does not have permissions to view.
|
| properties array: object | An array of property values for this folder. |
| propertyDefinitionId string | The unique identifier of the property definition that this value belongs to. |
| definition all of | The property definition metadata for this property value. |
| Property 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 all of | The relative URL to access this property definition. |
| 0 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. |
| propertyDefinition object | |
| * object | Contains server-side metadata for a Vault property definition, including datatype and naming. |
| id string | The unique identifier of the property definition. |
| url all of | The relative URL to access this property definition. |
| 0 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. |
Example
This example illustrates how to update lifecycle states for multiple folders.
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/folders:update-states' \
-X 'POST' \
-H 'Content-Type: application/json'\
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a...'\
-d '{
"updateLifecycleStateRequests": [
{
"entityUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/folders/2",
"lifecycleStateUrl": "/AutodeskDM/Services/api/vault/v2/vaults/9/lifecycle-states/2"
}
],
"comment": "Folder approved for release."
}'
Response
{
"results": [
{
"name": "11",
"id": "137",
"fullName": "$/11",
"category": "Project",
"categoryColor": -6710887,
"state": "Work in Progress",
"stateColor": -12859030,
"subfolderCount": 0,
"isLibrary": false,
"isCloaked": false,
"isReadOnly": false,
"lifecycleState": {
"id": "1",
"name": "Work in Progress",
"displayName": "Work in Progress",
"description": "State for free-form design creation and modifications",
"comments": [
"Available for editing",
"Change request"
],
"isDefault": true,
"color": -12859030,
"isReleasedState": false,
"isObsoleteState": false,
"displayOrder": 1,
"url": "/AutodeskDM/Services/api/vault/v2/vaults/9/lifecycle-states/1"
},
"createDate": "2026-03-26T09:05:48.15Z",
"createUserName": "Administrator",
"entityType": "Folder",
"url": "/AutodeskDM/Services/api/vault/v2/vaults/9/folders/137"
}
]
}