Request

Response

    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

    1. Create an upload session.
    2. Upload one or more raw content parts in order.
    3. Complete the upload and receive an upload ticket.
    4. Add the file with that upload ticket.

    Check in an existing file

    1. Create an upload session.
    2. Upload one or more raw content parts in order.
    3. Complete the upload and receive an upload ticket.
    4. Check out the file if it is not already checked out by the calling user.
    5. Check in the file with that upload ticket.

    Prerequisites

    1. Vault server 2027.2 or newer and Vault Data API v2 are available.
    2. You can authenticate and call API endpoints with a bearer token.
    3. 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-Length header (required; Vault returns 411 if it is missing).
    • The X-Vault-Upload-Session header 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
      }'
    
    Show More

    Request body fields:

    • uploadTicket (required for this walkthrough) — ticket from Step 3: Complete the Upload.
    • comment (optional) — check-in comment.
    • keepCheckedOut (optional, default false) — when true, 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. Inspect isCheckedOut in 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"
      }'
    
    Show More

    Required fields:

    • folderId — destination folder id (string; same as Folder.id from folder operations)
    • uploadTicket — ticket from Step 3: Complete the Upload
    • name — 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 partIndex 0. Do not replay the part in the original session.