Request

Response

    Categories
    POST

    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.

    Note that this endpoint is compatible with both BIM 360 and Forma projects.

    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
    * Required

    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.
    * Required

    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 parentId field to construct the tree locally instead of subcategoryIds.

    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"
          }'
    
    Show More

    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"
      ]
    }
    
    Show More