Upload and Check In a File
This walkthrough shows how to upload file content to Vault and either check in an existing file or add a new file using the Vault Data API v2 file upload channel. It is aligned with the desktop sample app File Upload tab, where the same upload, add, and check-in APIs are exposed for interactive testing.
The operations in this walkthrough are Beta endpoints available starting from Vault 2027.2. See About Beta Features before using them in your integration.
When to Use the Upload Channel
Use the upload channel when you need to:
- Stream raw file bytes to Vault without embedding content in a JSON request body.
- Check in replacement content for a checked-out file.
- Add a new file from uploaded content using a completed upload ticket.
Typical flows:
Add a new file
- Create an upload session.
- Upload one or more raw content parts in order.
- Complete the upload and receive an upload ticket.
- Add the file with that upload ticket.
Check in an existing file
- Create an upload session.
- Upload one or more raw content parts in order.
- Complete the upload and receive an upload ticket.
- Check out the file if it is not already checked out by the calling user.
- Check in the file with that upload ticket.
Prerequisites
- Vault server 2027.2 or newer and Vault Data API v2 are available.
- You can authenticate and call API endpoints with a bearer token.
- For check-in, the target file must be checked out by the calling user before you call check-in.
For authentication details, see Create Session with Vault Credentials.
Step 1: Create an Upload Session
Use Create File Upload with the file name so Vault can determine the content extension.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/file-uploads' \
-X 'POST' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d '{
"fileName": "Bracket.ipt"
}'
A 201 Created response indicates the upload session was created successfully.
Store the returned uploadId and uploadSessionToken. You need the token for every subsequent part upload and for completion.
Step 2: Upload Content Parts
Use Upload File Content Part starting with partIndex 0.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/file-uploads/{uploadId}/parts/0' \
-X 'PUT' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Length: {byteCount}' \
-H 'X-Vault-Upload-Session: {uploadSessionToken}' \
-H 'Authorization: Bearer {token}' \
--data-binary '@{localFilePath}'
Send the raw file bytes as the request body. Include:
- The
Content-Lengthheader (required; Vault returns411if it is missing). - The
X-Vault-Upload-Sessionheader with the token from the previous response.
Vault accepts a file MIME type as Content-Type but does not use that header to determine the file type. Do not send multipart/form-data; Vault returns 415 for multipart bodies.
Upload parts sequentially (0, 1, 2, …). Each part must not exceed maxPartSize from the upload session response. After each successful part upload, use the latest uploadSessionToken returned by the server for the next part.
A successful part upload returns 200 OK with an updated FileUploadSession body.
Step 3: Complete the Upload
Use Complete File Upload with the latest X-Vault-Upload-Session token.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/file-uploads/{uploadId}:complete' \
-X 'POST' \
-H 'X-Vault-Upload-Session: {uploadSessionToken}' \
-H 'Authorization: Bearer {token}'
A 200 OK response indicates the upload completed successfully. The response includes uploadTicket, size, and checksum. Pass uploadTicket to a subsequent check-in or add-file request.
Step 4: Check Out the File
Applies to the check-in flow only. Skip this step when adding a new file.
Use Check Out File on the file ID (the files/{id} identifier, not a file-version ID).
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/files/{fileId}:checkout' \
-X 'POST' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {token}'
A 200 OK response indicates the file was checked out. The response body is a FileVersion with isCheckedOut set to true.
Step 5: Check In the File
Applies to the check-in flow only.
Use Check In File on the checked-out file ID and include the uploadTicket in the request body.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/files/{fileId}:checkin' \
-X 'POST' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d '{
"uploadTicket": "{uploadTicket}",
"comment": "Updated bracket geometry",
"keepCheckedOut": false
}'
Request body fields:
uploadTicket(required for this walkthrough) — ticket from Step 3: Complete the Upload.comment(optional) — check-in comment.keepCheckedOut(optional, defaultfalse) — whentrue, keeps the file checked out after a successful check-in.
Interpret the response status as follows:
201 Created— Vault detected new content and created a new file version.200 OK— Check-in completed without creating a new version. InspectisCheckedOutin the response body:isCheckedOut=true— no content change was detected; the checkout was retained.isCheckedOut=false— no content change was detected; Vault released the unchanged checkout.
Alternative: Add a New File
To add a new file instead of checking in an existing one, use Add File after completing Step 3. Checkout is not required when adding a new file.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/files' \
-X 'POST' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d '{
"folderId": "1",
"uploadTicket": "{uploadTicket}",
"name": "Bracket.ipt",
"comment": "Initial check-in"
}'
Required fields:
folderId— destination folder id (string; same asFolder.idfrom folder operations)uploadTicket— ticket from Step 3: Complete the Uploadname— file name to create in Vault
Optional fields:
comment— initial check-in comment
On success, Vault returns 201 Created. The response includes a Location header with the URL of the new file.
See also Create Folder if you need to create the destination folder first. That operation also returns 201 Created with a Location header pointing to the new folder.
Notes
- The underlying Filestore upload is append-only. If a network failure leaves the outcome of a part upload unknown, create a new upload session from Step 1 and upload the file again from
partIndex0. Do not replay the part in the original session.