1. Operations
2. content
3. library
4. item
5. updatesession
6. file

## content library item updatesession file: add

Requests file content to be changed (either created, or updated). Depending on the source type of the file, this operation will either return an upload endpoint where the client can push the content, or the server will pull from the provided source endpoint. If a file with the same name already exists in this session, this operation will be used to update the content of the existing file.

When importing a file directly from storage, where the source endpoint is a file or datastore URI, you will need to have the ContentLibrary.ReadStorage privilege on the library item. If the file is located in the same directory as the library storage backing folder, the server will move the file instead of copying it, thereby allowing instantaneous import of files for efficient backup and restore scenarios. In all other cases, a copy is performed rather than a move.

### Request:

#### HTTP request

POST https://{server}/rest/com/vmware/content/library/item/updatesession/file/id:{update_session_id}?~action=add

#### Path Parameters

Name | Type | Description
--- | --- | ---
Required
update_session_id | string | Identifier of the update session to be modified.

#### Request Body Structure:

- JSON
- XML

{
"file_spec": {
"checksum_info": {
"algorithm": "SHA1",
"checksum": "string"
},
"name": "string",
"size": 1,
"source_endpoint": {
"ssl_certificate_thumbprint": "string",
"uri": "http://myurl.com"
},
"source_type": "NONE"
}
}
<?xml version="1.0" ?>
<ns0:Add-Input xmlns:ns0="http://vmware.com/content/library/item/updatesession/file" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<file_spec>
<source_endpoint>
<ssl_certificate_thumbprint>string</ssl_certificate_thumbprint>
<uri>http://myurl.com</uri>
</source_endpoint>
<name>string</name>
<source_type>NONE</source_type>
<checksum_info>
<checksum>string</checksum>
<algorithm>SHA1</algorithm>
</checksum_info>
<size>1</size>
</file_spec>
</ns0:Add-Input>

#### Request Body Parameters:

Name | Type | Description
--- | --- | ---
bold = required
file_spec | add_spec | Specification for the file that needs to be added or updated. This includes whether the client wants to push the content or have the server pull it.
file_spec.name | string | The name of the file being uploaded.
file_spec.source_type | string | The source type (`NONE`, `PUSH`, `PULL`) from which the file content will be retrieved. Defines how the file content is retrieved. Value is one of: NONE: No source type has been requested. PUSH: The client is uploading content using HTTP(S) PUT requests. PULL: The server is pulling content from a URL. The URL scheme can be `http`, `https`, `file`, or `ds`.
file_spec.source_endpoint | transfer_endpoint | Location from which the Content Library Service will fetch the file, rather than requiring a client to upload the file. Optional. It is only relevant when source_type has value PULL. This field is optional and it is only relevant when the value of `source_type` is PULL.
file_spec.source_endpoint.uri | URI | Transfer endpoint URI. The supported URI schemes are: `http`, `https`, `file`, and `ds`. An endpoint URI with the `ds` scheme specifies the location of the file on the datastore. The format of the datastore URI is: ds:///vmfs/volumes/uuid/path Some examples of valid file URI formats are: file:///path file:///C:/path file://unc-server/path When the transfer endpoint is a file or datastore location, the server can import the file directly from the storage backing without the overhead of streaming over HTTP.
file_spec.source_endpoint.ssl_certificate_thumbprint | string | Thumbprint of the expected SSL certificate for this endpoint. Only used for HTTPS connections. The thumbprint is the SHA-1 hash of the DER encoding of the remote endpoint's SSL certificate. If set, the remote endpoint's SSL certificate is only accepted if it matches this thumbprint, and no other certificate validation is performed. Optional. If not specified, standard certificate validation is performed.
file_spec.size | long | The file size, in bytes. Optional. If specified the server will verify it received the correct size.
file_spec.checksum_info | checksum_info | The checksum of the file. If specified, the server will verify the checksum once the file is received. If there is a mismatch, the upload will fail. Optional. If not specified the server does not verify the checksum.
file_spec.checksum_info.algorithm | string | The checksum algorithm (`SHA1`, `MD5`) used to calculate the checksum. Optional. If not specified the default checksum algorithm is SH_a1.
file_spec.checksum_info.checksum | string | The checksum value calculated with content.library.item.file.checksum_info.algorithm.

### Response:

#### HTTP Status Code: 200

#### Representations:

- JSON
- XML

{
"value": {
"bytes_transferred": 1,
"checksum_info": {
"algorithm": "SHA1",
"checksum": "string"
},
"error_message": {
"args": [
"string",
"string"
],
"default_message": "string",
"id": "string"
},
"name": "string",
"size": 1,
"source_endpoint": {
"ssl_certificate_thumbprint": "string",
"uri": "http://myurl.com"
},
"source_type": "NONE",
"status": "WAITING_FOR_TRANSFER",
"upload_endpoint": {
"ssl_certificate_thumbprint": "string",
"uri": "http://myurl.com"
}
}
}
<?xml version="1.0" ?>
<ns0:Add-Result xmlns:ns0="http://vmware.com/content/library/item/updatesession/file" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<value>
<source_endpoint>
<ssl_certificate_thumbprint>string</ssl_certificate_thumbprint>
<uri>http://myurl.com</uri>
</source_endpoint>
<status>WAITING_FOR_TRANSFER</status>
<error_message>
<default_message>string</default_message>
<id>string</id>
<args-array>
<array-item>string</array-item>
<array-item>string</array-item>
</args-array>
</error_message>
<name>string</name>
<upload_endpoint>
<ssl_certificate_thumbprint>string</ssl_certificate_thumbprint>
<uri>http://myurl.com</uri>
</upload_endpoint>
<source_type>NONE</source_type>
<bytes_transferred>1</bytes_transferred>
<checksum_info>
<checksum>string</checksum>
<algorithm>SHA1</algorithm>
</checksum_info>
<size>1</size>
</value>
</ns0:Add-Result>

#### Response Type:

Name | Type | Description
--- | --- | ---
bold = required
value | info | An content.library.item.updatesession.file.info structure containing upload links as well as server side state tracking the transfer of the file.
value.name | string | The name of the file.
value.source_type | string | The source type (`NONE`, `PUSH`, `PULL`) from which the file is being retrieved. This may be NONE if the file is not being changed. Defines how the file content is retrieved. Value is one of: NONE: No source type has been requested. PUSH: The client is uploading content using HTTP(S) PUT requests. PULL: The server is pulling content from a URL. The URL scheme can be `http`, `https`, `file`, or `ds`.
value.size | long | The file size, in bytes as received by the server. This field is guaranteed to be set when the server has completely received the file. Optional. This field won't be set until the file status is READY.
value.checksum_info | checksum_info | The checksum information of the file received by the server. Optional. If not specified the server does not verify the checksum.
value.checksum_info.algorithm | string | The checksum algorithm (`SHA1`, `MD5`) used to calculate the checksum. Optional. If not specified the default checksum algorithm is SH_a1.
value.checksum_info.checksum | string | The checksum value calculated with content.library.item.file.checksum_info.algorithm.
value.source_endpoint | transfer_endpoint | A source endpoint from which to retrieve the file. Optional. It is only relevant when source_type has value PULL. This field is optional and it is only relevant when the value of `source_type` is PULL.
value.source_endpoint.uri | URI | Transfer endpoint URI. The supported URI schemes are: `http`, `https`, `file`, and `ds`. An endpoint URI with the `ds` scheme specifies the location of the file on the datastore. The format of the datastore URI is: ds:///vmfs/volumes/uuid/path Some examples of valid file URI formats are: file:///path file:///C:/path file://unc-server/path When the transfer endpoint is a file or datastore location, the server can import the file directly from the storage backing without the overhead of streaming over HTTP.
value.source_endpoint.ssl_certificate_thumbprint | string | Thumbprint of the expected SSL certificate for this endpoint. Only used for HTTPS connections. The thumbprint is the SHA-1 hash of the DER encoding of the remote endpoint's SSL certificate. If set, the remote endpoint's SSL certificate is only accepted if it matches this thumbprint, and no other certificate validation is performed. Optional. If not specified, standard certificate validation is performed.
value.upload_endpoint | transfer_endpoint | An upload endpoint to which the client can push the content. Optional. It is only relevant when source_type has value PUSH. This field is optional and it is only relevant when the value of `source_type` is PUSH.
value.upload_endpoint.uri | URI | Transfer endpoint URI. The supported URI schemes are: `http`, `https`, `file`, and `ds`. An endpoint URI with the `ds` scheme specifies the location of the file on the datastore. The format of the datastore URI is: ds:///vmfs/volumes/uuid/path Some examples of valid file URI formats are: file:///path file:///C:/path file://unc-server/path When the transfer endpoint is a file or datastore location, the server can import the file directly from the storage backing without the overhead of streaming over HTTP.
value.upload_endpoint.ssl_certificate_thumbprint | string | Thumbprint of the expected SSL certificate for this endpoint. Only used for HTTPS connections. The thumbprint is the SHA-1 hash of the DER encoding of the remote endpoint's SSL certificate. If set, the remote endpoint's SSL certificate is only accepted if it matches this thumbprint, and no other certificate validation is performed. Optional. If not specified, standard certificate validation is performed.
value.bytes_transferred | long | The number of bytes of this file that have been received by the server.
value.status | string | The transfer status (`WAITING_FOR_TRANSFER`, `TRANSFERRING`, `READY`, `VALIDATING`, `ERROR`) of this file. Defines the transfer state of a file. Value is one of: WAITING_FOR_TRANSFER: Indicates that a file has been defined for a library item and its content needs to be uploaded. TRANSFERRING: Indicates that data is being transferred to the file. READY: Indicates that the file has been fully transferred and is ready to be used. VALIDATING: Indicates that the file is being validated (checksum, type adapters). ERROR: Indicates that there was an error transferring or validating the file.
value.error_message | localizable_message | Details about the transfer error. Optional. An error message is set if the status is ERROR.
value.error_message.id | string | Unique identifier of the localizable string or message template. This identifier is typically used to retrieve a locale-specific string or message template from a message catalog.
value.error_message.default_message | string | The value of this localizable string or message template in the `en_US` (English) locale. If vapi.std.localizable_message.id refers to a message template, the default message will contain the substituted arguments. This value can be used by clients that do not need to display strings and messages in the native language of the user. It could also be used as a fallback if a client is unable to access the appropriate message catalog.
value.error_message.args | string[] | Arguments to be substituted into a message template.

#### Errors:

HTTP Status Code | Type | Description
--- | --- | ---
400 | invalid_argument | if the `file_spec` is invalid.
404 | not_found | if the update session doesn't exist.
403 | unauthorized | if the caller doesn't have ContentLibrary.ReadStorage privilege on the library item of the update session and source type PULL is requested for a file or datastore source endpoint (that is, not HTTP or HTTPs based endpoint).