How to Upload Files to a vCenter Content Library Using REST APIs?
search cancel

How to Upload Files to a vCenter Content Library Using REST APIs?

book

Article ID: 446771

calendar_today

Updated On:

Products

VMware vCenter Server

Issue/Introduction

When performing automated operations or working in environments where the vSphere Client user interface is unavailable, administrators may need to upload files (such as ISOs, OVFs, or VMDKs) programmatically. Using the vCenter Content Library REST API allows for structured, scriptable file ingestion directly into designated content libraries.

Furthermore, this method can be leveraged to isolate underlying browser or network-layer constraints when executing uploads from jump hosts or directly from the vCenter Server Appliance.

Environment

VMware vCenter Server 8.x

Resolution

 

Prerequisites

  1. Create a Content Library within your vCenter Server instance.

  2. Navigate to your Content Library in the vSphere Client and extract the Library ID from the browser's address bar.

    • Example: If the URL is https://<VC_FQDN>/ui/app/content-libraries/cl/urn:vapi:com.vmware.content.Library:65e74fac-####-49a5-####-3b76d0334ee9:59d90142-..., the extracted Library ID is 65e74fac-####-49a5-####-3b76d0334ee9.

Step-by-Step API Execution Workflow

Open a secure terminal session and execute the following commands in sequence:

Step 1: Set Up Environment Variables

Define your vCenter fully qualified domain name (FQDN) and administrative credentials:

url='https://VC_FQDN'
username='administrator@vsphere.local'
password='########'
Step 2: Authenticate to vCenter Server

Establish an API session token using your predefined credentials:

session_id=`curl -X POST -k -H 'Content-Type: application/json' -u "$username:$password" "$url/rest/com/vmware/cis/session" | jq -r .value`
Step 3: Generate a Client Token

Generate a unique UUID identifier to guarantee request idempotency:

client_token=$(uuidgen)
Step 4: Create the Content Library Item

Initialize a new item entry within the target library. Substitute your copied library_id in the payload if different from the example:

curl -X POST -k \
-H 'Accept: application/json' -H "Content-Type: application/json" -H "vmware-api-session-id: $session_id" \
"$url/rest/com/vmware/content/library/item" \
-d '{  
  "client_token": "'$client_token'",
  "create_spec" : {
        "description" : "test item",
        "type" : "",
        "version" : "1",
        "content_version" : "obj-103",
        "library_id" : "65e74fac-####-49a5-####-3b76d0334ee9",
        "size" : 1,
        "cached" : true,
        "name" : "test-upload",
        "id" : "obj-103",
        "source_id" : "obj-103",
        "metadata_version" : "string"
    }
}' | jq -r ".value"

This command outputs the specific library_item_id (e.g., 86dbfd88-####-42b5-####-85b7bc854307).

Step 5: Establish an Update Session

Open a new active update session linked to your library_item_id generated in Step 4:

Bash
 
curl -X POST -k \
-H 'Accept: application/json' -H "Content-Type: application/json" -H "vmware-api-session-id: $session_id" \
"$url/rest/com/vmware/content/library/item/update-session" \
-d '{  
  "client_token": "'$client_token'",
  "create_spec" : {
        "library_item_id" : "86dbfd88-####-42b5-####-85b7bc854307",
        "client_progress" : null,
        "preview_info" : {
            "state" : "UNAVAILABLE"
        }
        "id" : "12345",
        "library_item_content_version" : "",
        "state" : "ACTIVE"
    }
}' | jq -r ".value"

This command outputs the update_session_id (e.g., e5f1abf6-####-4d0f-####-475525c1ef8a:59d90142-####-4b1b-####-4642fe2e0367).

Step 6: Define File Specifications and Source Type

Declare your upload parameters using the PUSH source type. Ensure the target filename retains its exact extension (e.g., .iso, .ovf, .vmdk):

Bash
 
curl -X POST -k \
-H 'Accept: application/json' -H "Content-Type: application/json" -H "vmware-api-session-id: $session_id" \
"$url/rest/com/vmware/content/library/item/updatesession/file/id:e5f1abf6-####-4d0f-####-475525c1ef8a:59d90142-####-4b1b-####-4642fe2e0367?~action=add" \
-d '{  
   "file_spec" : {
        "name" : "testfileupload.iso",
        "source_type" : "PUSH"
    }
}' | jq -r ".value"

The response exposes the upload_endpoint URI block required for data ingestion.

Step 7: Stream Payload to Upload Endpoint

Transmit the local binary file to the specific URI endpoint generated in Step 6 via an HTTP PUT operation:

curl --location -g --request PUT 'https://VC_FQDN:443/cls/data/20d85d75###########459693b/testfileupload.iso' -k \
--header 'Content-type: multipart/form-data' \
--form 'form-data=@"/Users/xxx/Downloads/small.iso"'
Step 8: Monitor Transfer Session Status

Poll the update session status to ensure the binary transfer completes successfully:

curl -X POST -k \  
-H 'Accept: application/json' -H "Content-Type: application/json" -H "vmware-api-session-id: $session_id" \
"$url/rest/com/vmware/content/library/item/updatesession/file/id:e5f1abf6-####-4d0f-####-475525c1ef8a:59d90142-####-4b1b-####-4642fe2e0367?~action=get" \
-d '{
    "file_name" : "testfileupload.iso"
}' | jq -r ".value"

Verify that the tracking parameter returns status: READY before proceeding.

Step 9: Commit the Session Changes

Explicitly commit the finalized state.

CRITICAL WARNING: This session complete action must be executed within 5 minutes of reaching a READY state. Failure to do so will cause the session to expire, invalidating the data transfer.

curl -X POST -k \
-H 'Accept: application/json' -H "Content-Type: application/json" -H "vmware-api-session-id: $session_id" \
"$url/rest/com/vmware/content/library/item/update-session/id:e5f1abf6-####-4d0f-8f02-####

Additional Information

For complete REST API endpoint schemas, refer to the Broadcom Developer Portal.

Powered by Wolken Software