categories
Creates a new category.
This endpoint creates a new category within a project’s category tree. The new category must be a child category of an existing category within the tree. This endpoint does not explicitly associate a status set or Asset custom attributes with the new category.
To assign a status set to a category, use PUT categories/:categoryId/status-step-set/:statusStepSetId. To assign an Asset custom attribute to a category, use PUT categories/:categoryId/custom-attributes/:customAttributeId.
Note that the new category will inherit a status set and any existing custom attributes from its parent
category. The status set may be overridden; the custom attributes may be added to.
To understand the basics of categories, category inheritance, and the Assets settings that define them, see the Assets Field Guide.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/bim360/assets/v1/projects/{projectId}/categories |
| Authentication Context | user context required |
| Required OAuth Scopes | data:write data:create |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via a three-legged OAuth flow. |
| Content-Type* string | Must be application/json |
Request
URI Parameters
| projectId string | The BIM 360 project ID. Must be a UUID or a project ID of the form “b.{UUID}”. |
Request
Query String Parameters
| includeUid boolean | If provided, and set to true, the globally-unique category uid field will be present in the response.
The globally unique category ID is used with the (upcoming) v3 category APIs. The option to include the
globally-unique ID with the v1 category APIs is to help consumers transition to the new IDs. |
Request
Body Structure
| name* string | The name of the category. Must be unique among children of the same parent category. This name is displayed for the category in the Assets user interface where a user chooses categories. |
| description string | A description of the category. |
| parentId* string | The ID of the new category’s parent category. |
Response
HTTP Status Code Summary
| 201 Created | Successfully created a new category. |
| 400 Bad Request | The request could not be understood by the server due to malformed syntax or missing request header |
| 401 Unauthorized | The request was not accepted because it lacked valid authentication credentials |
| 403 Forbidden | The request was not accepted because the client is authenticated, but is not authorized to access the target resource |
| 404 Not Found | The resource cannot be found |
| 409 Conflict | The request could not be completed due to a conflict with the current state of the target resource |
| 429 Too Many Requests | The request was not accepted because the rate limit was exceeded due to too many requests being made. |
| 500 Internal Server Error | An unexpected error occurred on the server |
Response
Body Structure (201)
| id string | The ID of the category. This is a numeric string for v1 category APIs. |
| createdAt string | The time when the component was created (ISO8601 Date time format in UTC). |
| createdBy string | The actor that created the component. This is an Autodesk / Oxygen ID. |
| updatedAt string | The time when the component was last updated (ISO8601 Date time format in UTC). |
| updatedBy string | The actor that last updated the component. This is an Autodesk / Oxygen ID. |
| deletedAt string | The time when the component was deleted at (ISO8601 Date time format in UTC). |
| deletedBy string | The actor that deleted the component. This is an Autodesk / Oxygen ID. |
| isActive boolean | A flag indicating whether the component is active or inactive (isActive is true if-and-only-if deletedAt is empty). |
| name string | The name of the category. Must be unique among children of the same parent category. This name is displayed for the category in the Assets user interface where a user chooses categories. |
| description string | A description of the category. |
| uid string | The globally-unique ID of a Category from the v3 (upcoming) Category APIs. This is provided
for interoperability with other APIs that use the globally-unique category ID. Only included if the
includeUid=true query param is included. |
| parentId string | The ID of the category’s parent category. |
| isRoot boolean | Whether or not this category is the root category of the category tree. If true, it’s the root; if
false, it’s not. There will only ever be one (immutable) root category for a project, which is created
automatically when the project is created. |
| isLeaf boolean | Whether or not this category is a leaf category of the category tree. If true, it’s a leaf; if false,
it’s not.
Note that this is a derived field and should not be persisted as this field may be updated without updating the category itself. |
| subcategoryIds array: string | An array of category IDs of this category’s child categories.
Note that this is a derived field and should not be persisted as this field may be updated without
updating the category itself. As such, it is highly recommended to use the |
Example
Successfully created a new category.
Request
curl -v 'https://developer.api.autodesk.com/bim360/assets/v1/projects/:projectId/categories?includeUid=true' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"name": "Electrical",
"description": "Electrical Outlets",
"parentId": "122"
}'
Response
{
"id": "123",
"createdAt": "2020-05-01T06:00:00.000Z",
"createdBy": "LA7ZL85MU7ML",
"updatedAt": "2020-05-01T06:00:00.000Z",
"updatedBy": "LA7ZL85MU7ML",
"deletedAt": "2020-05-01T06:00:00.000Z",
"deletedBy": "LA7ZL85MU7ML",
"isActive": true,
"name": "Electrical",
"description": "Electrical Outlets",
"uid": "b4511bcd-e141-4253-8607-26b194de4ae3",
"parentId": "122",
"isRoot": false,
"isLeaf": false,
"subcategoryIds": [
"124",
"125"
]
}