Upload Files to BIM 360 Document Management (new)
This tutorial demonstrates how to upload files to BIM 360 Document Management. The steps include finding the ID of the folder where you want to upload the files, creating an empty storage object for the file, generating a signed S3 URL, uploading the file to the signed URL, creating the first version of the file, and, optionally, creating additional versions of the file.
Note that you can upload any type of document to the BIM 360 Project Files folder or to a folder nested under the Project Files folder. However, you can only upload the following types of documents to the Plans folder or to a folder nested under the Plans folder: DWF, DWFX, DWG, IFC, PDF, RVT.
Note that if you upload PDF files to the Plans folder or to a folder nested under the Plans folder, BIM 360 Docs splits the file into separate pages (sheets) and assigns a separate ID to each page. In order to complete the upload process, you need to manually review and publish the file in BIM 360 Docs. For more details, see the Help documentation.
For more details about BIM 360 Document management, see the Data Management API.
Before You Begin
- Register an app, and select the Data Management and BIM 360 APIs.
- Acquire a 3-legged OAuth token with
data:createdata:readanddata:writescopes. - Verify that you have access to the relevant BIM 360 account, project, and folder.
Step 1: Find the Hub ID for the BIM 360 Account
The first few steps of the tutorial demonstrate how to create an empty storage object in the folder where you want to upload the file. This involves iterating through several Data Management endpoints to find the folder ID.
Call GET hubs to find the hub ID for the BIM 360 account that contains the folder you want to upload the file to.
Note that the BIM 360 account ID corresponds to a Data Management hub ID. To convert an account ID into a hub ID you need to add a “b." prefix. For example, an account ID of c8b0c73d-3ae9 translates to a hub ID of b.c8b0c73d-3ae9.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" "https://developer.api.autodesk.com/project/v1/hubs"
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/project/v1/hubs"
}
},
"data": [
{
"type": "hubs",
"id": "b.cGVyc29uYWw6cGUyOWNjZjMy",
"attributes": {
"name": "My First Account",
"extension": {
"type": "hubs:autodesk.bim360:Account",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.bim360:Account-1.0"
},
"data": {}
}
}
}
]
}
In this example, assume that the folder you want to upload the file to is in a hub called My First Account.
Find the hub (data.name), and note the hub ID - b.cGVyc29uYWw6cGUyOWNjZjMy.
Step 2: Find the Project ID
Use the hub ID (b.cGVyc29uYWw6cGUyOWNjZjMy) to call GET hubs/:hub_id/projects to get a list of all the projects in the hub. Find the project ID of the project that contains the folder you want to upload the file to.
Note that the project ID in BIM 360 corresponds to the project ID in the Data Management API. To convert a project ID in BIM 360 to a project ID in the Data Management API, you need to add a “b." prefix. For example, a project ID of a4be0c34a-4ab7 translates to a project ID of b.a4be0c34a-4ab7.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" "https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects"
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects"
}
},
"data": [
{
"type": "projects",
"id": "b.cGVyc29uYWw6d2l",
"attributes": {
"name": "My First Project",
"extension": {
"type": "projects:autodesk.core:Project",
"version": "1.0"
}
}
}
]
}
In this example, assume that My First Project is the project that contains the folder you want to upload the file to.
Find the project (data.attributes.name), and note the project ID (data.id) - b.cGVyc29uYWw6d2l.
Step 3: Find the Folder ID
Use the hub ID (b.cGVyc29uYWw6cGUyOWNjZjMy) and the project ID (b.cGVyc29uYWw6d2l) to call GET hubs/:hub_id/projects/:project_id/topFolders to get the Project Files folder or the Plans folder ID.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
"https://developer.api.autodesk.com/project/v1/hubs/b.cGVyc29uYWw6cGUyOWNjZjMy/projects/b.cGVyc29uYWw6d2l/topFolders"
Response
{
"jsonapi": {
"version": "1.0"
},
"data": [
{
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA",
"attributes": {
"name": "Project Files",
"displayName": "Project Files",
"createTime": "2017-07-17T13:06:56.0000000Z",
"createUserId": "",
"createUserName": "",
"lastModifiedTime": "2017-09-24T07:46:08.0000000Z",
"lastModifiedUserId": "X9WYLGPNCHSL",
"lastModifiedUserName": "John Smith",
"objectCount": 4,
"hidden": false,
"extension": {
"type": "folders:autodesk.bim360:Folder",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
},
"data": {
"visibleTypes": [
"items:autodesk.bim360:File"
],
"actions": [
"CONVERT"
],
"allowedTypes": [
"items:autodesk.bim360:File",
"folders:autodesk.bim360:Folder"
]
}
}
}
}
]
}
Find the folder (data.attributes.name); in this example, the Project Files folder, and note the folder ID (data.id) - urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA
Step 4: Find the Nested Folder ID
If you want to upload the document to a folder nested under the Project Files folder or the Plans folder, you need to call GET projects/:project_id/folders/:folder_id/contents repeatedly through the hierarchy of folders until you find the Folder ID of the folder you want to upload the document to. For the first iteration, use the Project Files ID (urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA) or the Plans folder ID.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
"https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/folders/urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA/contents"
Response
{
"jsonapi": {
"version": "1.0"
},
"data": [
{
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.QneBBX7evT2JSrpeQXga0",
"attributes": {
"name": "My First Files",
"displayName": "My First Files",
"createTime": "2017-07-17T13:06:56.0000000Z",
"createUserId": "",
"createUserName": "",
"lastModifiedTime": "2017-09-24T07:46:08.0000000Z",
"lastModifiedUserId": "X9WYLGPNCHSL",
"lastModifiedUserName": "John Smith",
"objectCount": 4,
"hidden": false,
"extension": {
"type": "folders:autodesk.bim360:Folder",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/folders:autodesk.bim360:Folder-1.0"
},
"data": {
"visibleTypes": [
"items:autodesk.bim360:File"
],
"actions": [
"CONVERT"
],
"allowedTypes": [
"items:autodesk.bim360:File",
"folders:autodesk.bim360:Folder"
]
}
}
}
}
]
}
In this example, assume that My First Files is the folder that contains the file you want to download.
Find the folder (data.attributes.name), and note the folder ID (data.id) - urn:adsk.wipprod:fs.folder:co.QneBBX7evT2JSrpeQXga0.
Step 5: Create a Storage Object
Use the project ID (b.cGVyc29uYWw6d2l) and the folder ID (urn:adsk.wipprod:fs.folder:co.QneBBX7evT2JSrpeQXga0) to call POST projects/:project_id/storage to create an empty storage object for the file in the folder.
Note that you need to assign a filename and file extension (PNG or JPG) to the name parameter (My First File.jpg).
Request
curl -X POST -H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json" -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT"
"https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/storage"
-d '{
"jsonapi": { "version": "1.0" },
"data": {
"type": "objects",
"attributes": {
"name": "My First File.jpg"
},
"relationships": {
"target": {
"data": { "type": "folders", "id": "urn:adsk.wipprod:fs.folder:co.QneBBX7evT2JSrpeQXga0" }
}
}
}
}'
Repsonse
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg",
"relationships": {
"target": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.mgS-lb-BThaTdHnhiN_mbA"
}
}
}
}
}
Note the object ID (data.id) - urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg.
The object ID includes the following sections: <urn:adsk.objects:os.object>:<bucket key>/<object key>
Note the bucket key - wip.dm.prod and the object key - 2a6d61f2-49df-4d7b.jpg
Step 6: Generate a Signed S3 URL
Use the bucket key (wip.dm.prod) and the object key (2a6d61f2-49df-4d7b.jpg) to call GET buckets/:bucketKey/objects/:objectKey/signeds3upload to generate a signed URL for the storage object.
This endpoint supports generating multiple signed URLs, which allows you to upload multiple chunks of the same file in parallel. For more information, see GET signeds3upload.
Request
curl -X GET -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/2a6d61f2-49df-4d7b.jpg/signeds3upload"
Repsonse
{
"uploadKey": "AQICAHifrJ6-BSHUmjAat4..........QWI-fuvghN23akgePMdmykV",
"uploadExpiration": "2022-02-05T00:00:00Z",
"urlExpiration": "2022-02-03T05:23:29Z",
"urls": [
"https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/26668812-6bb1-4f80-bab2-09776f24fd98?uploadId=[UPLOAD_ID]&partNumber=1&X-Amz-Security-Token=[AMZ_TOKEN]%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220203T052230Z&X-Amz-SignedHeaders=host&X-Amz-Expires=60&X-Amz-Credential=[AMZ_CREDENTIAL]%2F20220203%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=[AMZ_SIGNATURE]"
]
}
Note the uploadKey and the urls response attributes.
Step 7: Upload a File to the Signed URL
To upload the file to the signed URL, use a PUT method and the urls attribute as the URI.
Note that you should not use a bearer token with this call.
Request
curl -X PUT --data-binary @D:\My First File.jpg "https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/26668812-6bb1-4f80-bab2-09776f24fd98?uploadId=[UPLOAD_ID]&partNumber=1&X-Amz-Security-Token=[AMZ_TOKEN]%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220203T052230Z&X-Amz-SignedHeaders=host&X-Amz-Expires=60&X-Amz-Credential=[AMZ_CREDENTIAL]%2F20220203%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=[AMZ_SIGNATURE]"
Note that a successful call (200) returns an empty response.
Step 8: Complete the Upload
Use the bucket key (wip.dm.prod) the object key (2a6d61f2-49df-4d7b.jpg`) and the upload key (AQICAHifrJ6-BSHUmjAat4..........QWI-fuvghN23akgePMdmykV) to call POST buckets/:bucket_key/objects/:object_key/signeds3upload to complete the upload.
This endpoint needs to be called within 24 hours from the time you began uploading the file.
Request
curl -X POST -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" --data-raw '{"uploadKey":"AQICAHifrJ6-BSHUmjAat4..........QWI-fuvghN23akgePMdmykV"}' "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/2a6d61f2-49df-4d7b-9aed-439586d61df7.jpg/signeds3upload"
Repsonse
{
"bucketKey" : "wip.dm.prod",
"objectId" : "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b-9aed-439586d61df7.jpg",
"objectKey" : "2ac28abc-9f6e-463d-bcc4-5c194d552beb.jpg",
"size" : 879394,
"contentType" : "application/octet-stream",
"location" : "https://developer.api.autodesk.com/oss/v2/buckets/wip.dm.prod/objects/2a6d61f2-49df-4d7b-9aed-439586d61df7.jpg"
}
The file has been uploaded to the storage object.
Step 9: Create the First Version of the File
Use the project ID (b.cGVyc29uYWw6d2l), the folder ID (urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA), and the Object ID (urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg) to call POST projects/:project_id/items to create the first version of the uploaded file.
Note that if you upload PDF files to the Plans folder or to a folder nested under the Plans folder, BIM 360 Docs splits the file into separate pages (sheets) and assigns a separate ID to each page. In order to complete the upload process, you need to manually review and publish the file in BIM 360 Docs. For more details, see the Help documentation.
Request
curl -X POST -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" -H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json"
"https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/items" -d '{
"jsonapi": { "version": "1.0" },
"data": {
"type": "items",
"attributes": {
"displayName": "My First File.jpg",
"extension": {
"type": "items:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"tip": {
"data": {
"type": "versions", "id": "1"
}
},
"parent": {
"data": {
"type": "folders",
"id": "urn:adsk.wipprod:fs.folder:co.BJU3PTc4Sd2CmXM492XUiA"
}
}
}
},
"included": [
{
"type": "versions",
"id": "1",
"attributes": {
"name": "My First File.jpg",
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"storage": {
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/2a6d61f2-49df-4d7b.jpg"
}
}
}
}
]
}'
Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/items"
}
},
"data": {
"type": "items",
"id": "urn:adsk.wipprod:dm.lineage:AeYgDtcTSuqYoyMweWFhhQ",
"attributes": {
"displayName": "My First File.jpg",
"createTime": "2016-05-30T15:32:05+00:00",
"createUserId": "KPN8P8P65K",
"createUserName": "John Smith",
"lastModifiedTime": "2016-05-30T15:32:05+00:00",
"lastModifiedUserId": "KPN8P8P65K",
"lastModifiedUserName": "John Smith",
"extension": {
"type": "items:autodesk.core:File",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/items%3Aautodesk.core%3AFile-1.0"
},
"data": {}
}
},
"included": [
{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.AeYgDtcTSuqYoyMweWFhhQ?version=1",
"attributes": {
"name": "My First File.jpg",
"displayName": "My First File.jpg",
"createTime": "2016-05-30T15:32:05+00:00",
"createUserId": "KPN8P8P65K",
"createUserName": "John Smith",
"lastModifiedTime": "2016-05-30T15:32:05+00:00",
"lastModifiedUserId": "KPN8P8P65K",
"lastModifiedUserName": "John Smith",
"versionNumber": 1,
"mimeType": "application/image",
"fileType": "jpg",
"storageSize": 879394,
"extension": {
"type": "versions:autodesk.core:File",
"version": "1.0",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/versions%3Aautodesk.core%3AFile-1.0"
},
"data": {}
}
}
}
]
}
}
Note the item ID (data.id) - urn:adsk.wipprod:dm.lineage:AeYgDtcTSuqYoyMweWFhhQ, and version ID (inlcuded[id]) - urn:adsk.wipprod:fs.file:vf.AeYgDtcTSuqYoyMweWFhhQ?version=1.
Step 10: Create Additional Versions of the File
To create an additional version of the file, you need to create a new storage object (step 5), upload the new version to the object (step 6), and use the item ID you retrieved in step 7 to call POST projects/:project_id/versions.
Request
curl -X POST -H "Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT" -H "Content-Type: application/vnd.api+json" -H "Accept: application/vnd.api+json" -d '{
"jsonapi": { "version": "1.0" },
"data": {
"type": "versions",
"attributes": {
"name": "New Version of My First File.jpg",
"extension": { "type": "versions:autodesk.bim360:File", "version": "1.0"}
},
"relationships": {
"item": { "data": { "type": "items", "id": "urn:adsk.wipprod:dm.lineage:AeYgDtcTSuqYoyMweWFhhQ" } },
"storage": { "data": { "type": "objects", "id": "<new_object_ID>" } }
}
}
}' "https://developer.api.autodesk.com/data/v1/projects/b.cGVyc29uYWw6d2l/versions"
Response
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.1HROnsnfQgq4N0b-nUoGge?version=2",
"attributes": {
"name": "New Version of My First File.jpg",
"displayName": "new version of my first file.jpg",
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0",
"data": {}
}
},
"relationships": {}
},
"included": [
{
"type": "items",
"id": "urn:adsk.wipprod:dm.lineage:AeYgDtcTSuqYoyMweWFhhQ",
"attributes": {
"extension": {
"type": "items:autodesk.bim360:File",
"version": "1.0",
"data": {}
}
},
"links": {},
"relationships": {
"tip": {
"data": {
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.1HROnsnfQgq4N0b-nUoGge?version=2"
},
"links": {}
},
"versions": {},
"parent": {},
"refs": {},
"links": {}
}
}
]
}