categories/:categoryId/relationships
Creates relationships between a single category and one or more entities in other domains within a project.
This endpoint accepts a category ID and an array of one or more entities with which to link.
It creates a separate relationship between the category and each of the entities in turn, and returns an array with a description of each of the new relationships.
Within BIM 360 projects, Categories may only link to entities of entity type checklisttemplate
.
To understand the basics of relationships, 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/{categoryId}/relationships |
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}”. |
categoryId string | The category ID |
Request
Body Structure
Request payload for adding relationships between a Category and target entities
entities array: object | An array of entities in other domains to link to the specified category. |
id* string | The ID of the related entity. |
type* enum:string | The entity type of the entity to link.
Within BIM 360 projects, the only allowable type is Specifying any other entity types will return a |
relationshipId string | (Internal use only.) An externally-generated unique UUID for the new relationship. Should not be supplied, in which case the Relationship service will generate the ID and it will be returned by this endpoint. |
Response
HTTP Status Code Summary
201 Created | Successfully created new category relationships. |
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: UUID | The relationship ID, a GUID that uniquely identifies the relationship. |
createdOn datetime: ISO 8601 | The date and time that the relationship was created. |
isReadOnly boolean | Indicates whether this relationship is read-only for the current caller. If true , the relationship is
read-only. If false , it is not. |
isService boolean | Indicates whether or not this relationship was created by a service. If true , it was created by a service.
If false , it was not. |
isDeleted boolean | Indicates whether this relationship is deleted. If true , it is deleted. If false , it is not. |
deletedOn datetime: ISO 8601 | The date and time that the relationship was deleted. |
entities array: object | An array of the two domain entities contained in the relationship. |
createdOn datetime: ISO 8601 | The date and time that the domain entity was created. |
domain string | The domain that the domain entity is a part of.
Max length: 128 |
type string | The type of the domain entity.
Max length: 128 |
id string | The identifier of the domain entity.
Max length: 128 |
Example
Successfully created new category relationships.
Request
curl -v 'https://developer.api.autodesk.com/bim360/assets/v1/projects/:projectId/categories/123/relationships' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"entities": [
{
"id": "0212fd8b-8682-465c-a64a-c1dc9a488030",
"type": "checklisttemplate",
"relationshipId": "52d7cecf-9f88-4aa2-b725-a6e09a0bc549"
}
]
}'
Response
[
{
"id": "52d7cecf-9f88-4aa2-b725-a6e09a0bc549",
"createdOn": "2020-05-01T06:00:00.000Z",
"isReadOnly": false,
"isService": true,
"isDeleted": false,
"deletedOn": "2020-05-01T06:00:00.000Z",
"entities": [
{
"createdOn": "2020-05-01T06:00:00.000Z",
"domain": "autodesk-bim360-issue",
"type": "issue",
"id": "0212fd8b-8682-465c-a64a-c1dc9a488030"
}
]
}
]