Request

Response

    Create an App-Managed Bucket and Upload a File

    This walkthrough explains how to create a bucket managed by your app and upload a file to that bucket.

    Before You Begin

    Make sure that you have registered an app and successfully acquired an OAuth token with scopes bucket:create, bucket:read, and data:write. This will allow you to create a bucket, get bucket details, and upload a file.

    Step 1: Create a bucket

    Before uploading a file, create a bucket and set a retention policy using the POST buckets endpoint. In our example, we’re going to create a transient bucket, meaning that anything uploaded to it will be deleted after 24 hours.

    Example

    curl -v 'https://developer.api.autodesk.com/oss/v2/buckets'
      -X 'POST'
      -H 'Content-Type: application/json'
      -H 'Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i'
      -d '
        {
          "bucketKey":"mybucket",
          "policyKey":"transient"
        }
        '
    
    Show More

    Once the bucket is created, verify that it exists using the GET buckets/:bucketKey/details endpoint:

    curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/details'
      -X 'GET'
      -H 'Authorization: Bearer GX6OONHlQ9qoVaCSmBqJvqPFUT5i'
    

    If successful, the response body should look something like this:

    {
      "bucketKey": "mybucket",
      "bucketOwner": "obQDn8P0GanGFQha4ngKKVWcxwyvFAGE",
      "createdDate": 1401735235495,
      "permissions": [
        {
          "authId": "obQDn8P0GanGFQha4ngKKVWcxwyvFAGE",
          "access": "full"
        }
      ],
      "policyKey": "transient"
    }
    
    Show More

    Step 2: Initiate a direct to s3 multipart upload

    Choose a name for your object. This can be the actual filename or something like a GUID generated by a data management system, but maintain the file extension. For this example we will assume a 20Mb file named skyscpr1.3ds

    The GET buckets/:bucketKey/objects/:objectKey/signeds3upload requests one or multiple S3 signed URL with which to upload an object based on how many ‘parts’ you specify. These URLs will directly transmit the file to S3 and will be registered in OSS once POST buckets/:bucketKey/objects/:objectKey/signeds3upload is called.

    Example

    curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds/signeds3upload?parts=2'
      -X GET
      -H 'Authorization: Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi'
      -H 'Content-Type: application/json'
    

    If successful, the response body should look something like this:

    {
      "uploadKey": "{UPLOAD_KEY}",
      "uploadExpiration": "2022-01-25T00:00:00Z",
      "urlExpiration": "2022-01-23T21:48:42Z",
      "urls": [
        "https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=1&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=269cde4288e380ce720b2a8a039b5e311cb9d4276ccf5e59582b32676a8f378b",
        "https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=2&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=e5e4edcf819856f4a689c8a90975a64395df7fb33d60e3ab351e39ad0fe2585c"
      ]
    }
    
    Show More

    Step 3: Split the file, and upload.

    If using CURL you will have to have the object as distinct files. At this point you should split the file into those chunks (minimum 5Mb filesize)

    split -b 10m -d skyscpr1.3ds part
    

    The upload can then be performed to the URLs received from Step 2.

    Note: These uploads do not use an ‘Authorization’ header.

    curl -v 'https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=1&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=269cde4288e380ce720b2a8a039b5e311cb9d4276ccf5e59582b32676a8f378b'
      -X 'PUT'
      -H 'Content-Type: application/octet-stream'
      -H 'Content-Length: 10485760'
      -T 'part00'
    
    curl -v 'https://com-autodesk-oss-direct-upload.s3-accelerate.amazonaws.com/signed-url-uploads/647eac4c-538a-430f-aeb9-f9868c812f0a?uploadId=DMgAHXjzyxNyetLEdTxBOGmtAglxYcvCiSdzJGeXlxrELy6LV1u5sV1vJMomNA1ajJLU_Si7MYFsZ2mAvQbrgBl32AKD1ZQ25dgZl0DJsMbEqfC_AciKZWGryKcW.WwzlUXJrbqLSzzqAolhoGDm0A--&partNumber=2&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQD5Kzy1P6NLaYATv93vjMe4xlBvvYXZQCNjWMmASGM%2FKgIhAPQVE0Qjg4muudsXUCgp%2BMcR%2F6Xu8WSPDgEpsDN34m0EKoMECPX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMOTkzNzg5OTkyMDYzIgz7JvvTxzNi3xf3K8Aq1wOKZgmdUjLUXjBwryTukT8udQWjmR7nTXydT09euWNE7Sh%2FVztSQhXDXpBXp%2B9%2Ffpyw7CyZJOoJJgqH0DfgqIglXTP%2FUnT7cG89AIryNVDa3Tndtb1P1IlLjf0T%2BWMCXw0U%2BryS5%2BMngDrw5O82e2qeAWPcCJjo0X1SWg%2FzWac44I6vqH02U0dZoQQ%2Bu3n9yiI4DtWMj60wjgt%2FgjGmSY5jD2mILpvOSJpHvtai6%2BMCbQOstEEc6OaY1LeOBlf3Pf8SEfrpHGsHw%2BhJQ5RlpEcudX2ZO8LdZjk44%2FH6INdISZJr4N8gKKBG5%2FiXmOI4qzwcydNgfYJ3lN7yt7YRntBPnJ2N3EmKOPMot%2B0OCk7DFS%2F0f2JbcJCEB%2Bmg2tWG5KqV9tu968SR%2FkC4l2LAyo4ZVRLhQTOWgSYbfhYTL1F%2BIGGWE%2Fi%2BzGYSXKthrVYpC4h7eSeFK%2B3FUQSb6lJ0yScRP%2B%2FRmy6W%2FynJC8F%2BFkYLT%2FJaFE8tKgTUdphHtat0zppFp5UzrOQePc1abSg2uMpKkjvUSt%2FrvJ3WuN7UBj2LQ1ruUV6nx7rS7fSOUazOXmP5ToY5SXbAEx5Dvc9hEyBkxct9ZhbaF5mJE4yQbfn20xaMw73%2Bzvsw0b%2FshwY6pAH8uiCdcXXWNsEYc2g0T7H6fuCFE19VflTSlmBVnGLRTho0y4kCX6k4VIn6xV2dbuTAZzB8U%2Fdms%2FkgIM29DXNdJuJgskulKDnMjK7rRQUe44MUQoxx2P20M8pX0Oq5epgKRGtqxi6%2F8XFh5mJRVhamJwu59WmvLdSvGVsbGJk3oYtTmyEJn4N0or2QWbZdFtfrBGhLlm%2FuTislKvcut0uDWixBfA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210723T214743Z&X-Amz-SignedHeaders=host&X-Amz-Expires=120&X-Amz-Credential=[AMZ CREDENTIAL]&X-Amz-Signature=e5e4edcf819856f4a689c8a90975a64395df7fb33d60e3ab351e39ad0fe2585c'
      -X 'PUT'
      -H 'Content-Type: application/octet-stream'
      -H 'Content-Length: 10485760'
      -T 'part01'
    
    Show More

    Step 4: Complete the upload

    Call the POST buckets/:bucketKey/objects/:objectKey/signeds3upload endpoint to complete the multipart upload and register the item with OSS.

    curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds/signeds3upload'
      -X POST
      -H 'Authorization: Bearer eYeL5gYxAT2j3u9TEerxoJoToNbi'
      -H 'Content-Type: application/json'
      -H 'x-ads-meta-Content-Type: application/octet-stream'
      --data-raw '{
        "uploadKey": "{UPLOAD_KEY}"
      }'
    
    Show More

    If successful, the response body should look like this:

    {
      "bucketKey" : "mybucket",
      "objectId" : "urn:adsk.objects:os.object:mybucket/skyscpr1.3ds",
      "objectKey" : "skyscpr1.3ds",
      "sha1" : "e84021849a9f5d1842bf792bbcbc6445c280e15b",
      "size" : 20971520,
      "content-type": "application/octet-stream",
      "location": "https://developer.api.autodesk.com/oss/v2/buckets/mybucket/objects/skyscpr1.3ds"
    }
    
    Show More