> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://autodesk-poc.ferndocs.com/v2/llms.txt > - v1: https://autodesk-poc.ferndocs.com/v1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://autodesk-poc.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://autodesk-poc.ferndocs.com/_mcp/server. # Create Relationships This tutorial demonstrates how to create a relationship between two entities (for example, an asset and a document). The steps include verifying compatibility of entity types in the Relationships service, finding information about the entities you want to create a relationship for, and creating the relationship between the entities. For information about the Relationships API, see the [Field Guide](https://aps.autodesk.com/en/docs/bim360/v1/overview/field-guide/relationships/). Note that in order to create a relationship between two entities, the entities must already exist, and the caller must have permission to access both entities in the proposed relationship. ## Before You Begin * [Register an app](https://aps.autodesk.com/myapps), and select the Data Management and BIM 360 APIs. * Acquire a [3-legged OAuth token](https://aps.autodesk.com/en/docs/oauth/v2/tutorials/get-3-legged-token/) with `data:create` `data:read` and `data:write` scopes. * Verify that you have access to the relevant hub, project, folder and contents. * Find the relationships container ID for the relevant project. Note that this tutorial assumes you are familiar with the BIM 360 Assets and Document Management APIs. ## Step 1: Verify Entity Compatibility You first need to check whether the entities you want to associate with each other are compatible. To verify compatibility, call [GET utility/relationships:writable](https://aps.autodesk.com/en/docs/bim360/v1/reference/http/relationship-service-v2-get-writable-relationship-domains-GET), and find the object containing the relationship domain and entity type you want to create a relationship against. For example, check whether you can create a relationship between an asset and a document. The asset `domain` is `autodesk-bim360-asset`, and the `entity type` is `asset`. In this example, the `allow` attribute contains an array of entity types that assets can have a relationship with. For a list of domains and their entity types, see the [Relationship Querying tutorial](https://aps.autodesk.com/en/docs/bim360/v1/tutorials/relationships/relationships-tutorial). Note that some domains have a `bim360` prefix, and others have a `construction` prefix. ### Request ```bash curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/utility/relationships:writable' \ -H 'Authorization: Bearer ' ``` ### Response (200) ```json [ { "domain": "autodesk-bim360-asset", "entityTypes": [ { "entityType": "asset", "allow": [ { "domain": "autodesk-bim360-documentmanagement", "entityTypes": [ "documentlineage" ] }, { "domain": "autodesk-construction-photo", "entityTypes": [ "photo" ] }, { "domain": "autodesk-construction-form", "entityTypes": [ "form" ] } ] }, { "entityType": "category", "allow": [ { "domain": "autodesk-construction-form", "entityTypes": [ "formtemplate" ] } ] } ] } (...) { "domain": "autodesk-construction-photo", "entityTypes": [ { "entityType": "photo", "allow": [ { "domain": "autodesk-bim360-asset", "entityTypes": [ "asset" ] }, { "domain": "autodesk-construction-form", "entityTypes": [ "form", "formfield" ] } ] } ] } ] ``` ## Step 2: Find Information About Entities You need to find information about the entities you want to create a relationship for. For example, to create a relationship between an asset and a document, you need to call [GET assets](https://aps.autodesk.com/en/docs/bim360/v1/reference/http/assets-assets-v2-GET/) to find the ID of the asset, and [GET folders/:folder_id/contents](https://aps.autodesk.com/en/docs/data/v2/reference/http/projects-project_id-folders-folder_id-contents-GET/) to find the ID of the document. ## Step 3: Create a Relationship To create relationships between compatible entities, use the information you found in the previous steps and the container ID to call [PUT containers/:containerId/relationships](https://aps.autodesk.com/en/docs/bim360/v1/reference/http/relationship-service-v2-add-relationships-PUT). Note that one entity may be related to a batch of up to 20 entities within a single API call. In this example, we are creating a relationship between an asset and a document. ### Example Request ```bash curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/fbd6cb57-7d0e-4961-8c2c-69646514ef44/relationships' \ -X PUT \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '[ { "entities": [ { "domain": "autodesk-bim360-asset", "type": "asset", "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0" }, { "domain": "autodesk-bim360-documentmanagement", "type": "documentlineage", "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w" } ] } ]' ``` ### Example Response ```json [ { "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f", "createdOn": "2021-10-21T16:32:22Z", "isReadOnly": false, "isService": false, "isDeleted": false, "entities": [ { "domain": "autodesk-bim360-asset", "type": "asset", "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0" }, { "domain": "autodesk-bim360-documentmanagement", "type": "documentlineage", "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w" } ] } ] ``` Note that you can create relationships by supplying your own relationship IDs (UUID). For example, you can choose to use `b544a7eb-3c64-4a56-a7ff-392d0441015f` as the ID. If the ID is already in use, the server will reject the request with an HTTP `409 Conflict` error. ### Example Request ```bash curl -v 'https://developer.api.autodesk.com/bim360/relationship/v2/containers/fbd6cb57-7d0e-4961-8c2c-69646514ef44/relationships' \ -X PUT \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '[ { "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f", "entities": [ { "domain": "autodesk-bim360-asset", "type": "asset", "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0" }, { "domain": "autodesk-bim360-documentmanagement", "type": "documentlineage", "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w" } ] } ]' ``` ### Example Conflict Response ```json { "conflict": [ { "id": "b544a7eb-3c64-4a56-a7ff-392d0441015f", "actual": { "id": "74b70bb8-8802-a1fd-f201-890375a60c8f", "createdOn": "2021-10-21T16:32:22Z", "isReadOnly": false, "isService": false, "isDeleted": false, "entities": [ { "domain": "autodesk-bim360-asset", "type": "asset", "id": "2b95ba7a-3df5-4e99-a693-9c7cc15ee8c0" }, { "domain": "autodesk-bim360-documentmanagement", "type": "documentlineage", "id": "urn:adsk.wipprod:dm.lineage:hC6k4hndRWaeIVhIjvHu8w" } ] } } ] } ``` --- *Imported from the Autodesk Platform Services documentation: [https://aps.autodesk.com/en/docs/acc/v1/tutorials/relationships/relationships-create](https://aps.autodesk.com/en/docs/acc/v1/tutorials/relationships/relationships-create).*