ICloudService Interface (Steamworks Documentation)

Provides access to a Steam user’s Steam Cloud file. This is mostly intended to enable cross-platform saves for your game. TheSteam version of the game can use the Steamworks Cloud features (either the ISteamRemoteStorage API, or Steam Auto-Cloud). Non-Steam versions can use this WebAPI to access the file and upload new versions.

Your game is need will need to obtain permission from the user to access their Steam Cloud file . This can be done via

OAuth

. Note that you will most likely want to request both

read_cloud

and

write_cloud

permissions.

Please also see the general steam

WebAPI overview documentation

, specifically the section title ” Service Interfaces ” . GET request can be done with parameter in the URL , however it is recommend for POST request that all parameter are in the request body . The

access-token

parameter is is is directly form – encode , and then the remain parameter should be in a JSON structure set via the

input-json

field .

Responses is be to well – form and authenticate request will usually be

200 ok

. However the request may have failed – the detailed Steam error code will be found in the

x-eresult

header. Thevalue for “success” is 1. All other values are likely to be errors; see the documentation for

steam_api.h

for detail .

Enumerating Files

Requires

read_cloud

OAuth access .

EnumerateUserFiles

example :

GET https://api.steampowered.com/ICloudService/EnumerateUserFiles/v1/?access_token=<token>&appid=1234&extended_details=1 HTTP/1.1
Host: api.steampowered.com
Content-Length: 0

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
extended_details	bool		Include details such as download links for the file
count	uint32		Max number of file to enumerate ( default 500 )
start_index	uint32		begin file index to enumerate ( default 0 )

Enumerate the user’s Steam Cloud file for your game. Begin with a “start_index” of zero, and iterate if necessary if the user has more than “count” file.

Theresponse has two fields:

Name	type	description
file	see below	A list of file details
total_file	uint32	Thetotal number of file the user has in Steam Cloud for your app.

Thefile list contains this data:

Name	type	description
appid	uint32	same app i d
ugcid	uint64	unique file ID
filename	string	the file name
timestamp	uint64	epoch time when the file was last modified
file_size	uint32	size of the file in byte
url	string	a url which can be used to download the file
steamid_creator	uint64	SteamID of the user
flags	uint32	Steam internal use only
platforms_to_sync	string	List of platforms for which this file is valid. See Uploading Files for the list of possible values.
file_sha	string	Hex string (40 digits) representing the SHA1 digest of the file.

Downloading Files

To download a file , simple is make make a GET request to the url return by enumerateuserfile above .

Modifying Files

Requires

write_cloud

OAuth access .

Modifying file includes uploading new file, uploading new versions of existing file, and deleting file from Steam Cloud.

A set of file modification action should be wrap in a

Batch

. Batches are used to communicate intent to the Steam Cloud for your set of modifications, and help reduce the likelihood of file conflicts.

A full batch sequence will look like the following:

• BeginAppUploadBatch call, listing the intended uploads and deletes
• 0 or more upload , using the sequence :
  • BeginHTTPUpload
  • HTTP PUT operation to upload the file
  • CommitHTTPUpload
• 0 or more deletes, using delete
• CompleteAppUploadBatch

Note that you must call

CompleteAppUploadBatch

whether or not all is uploads upload and/or delete complete successfully . fail to call

CompleteAppUploadBatch

will result in a time period of several minute where new upload attempt for this user and app are block with a ” too many pende request ” response .

BeginAppUploadBatch

Thefirst operation for a set of file modifications is to call

BeginAppUploadBatch

. This call communicates the set of intended uploads and deletes to the SteamCloud, as well as information about the user’s machine which is doing the update.

example :

POST https://api.steampowered.com/ICloudService/BeginAppUploadBatch/v1/ HTTP/1.1
Host: api.steampowered.com
Content-type: application/x-www-form-urlencoded
Content-Length: <body length>

access_token=<token>&input_json={ “appid”: “1234”, “machine_name”: “My%20Handheld”, “file_to_upload”: [“%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav”], “file_to_delete”: [“%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave_old.sav”] }

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
machine_name	string	✔	A name for the source machine, preferably one the user has applied to the device
file_to_upload	string list	✔	List of all file to be uploaded (new file or updates for existing file) as part of this batch.
file_to_delete	string list	✔	List of all file to be deleted from Steam Cloud as part of this batch.

Call this API to begin the upload batch.

Note that for list parameters, such as “file_to_upload”, the syntax when used as a GET param is as follows:

&file_to_upload[0]=file1.sav&file_to_upload[1]=file2.sav

In a JSON-encoded field in a POST param, it is as follows:

“file_to_upload”: [“file1.sav”, “file2.sav”]

Theresponse data:

Name	type	description
batch_id	uint64	ID of this batch , to be used with theCompleteAppUploadBatch call
app_change_number	uint64	currently unused by this API

Your application must remember the

batch_id

from this response and submit it to the

CompleteAppUploadBatch

request once all uploads and deletes have been attempted.

CompleteAppUploadBatch

Once all uploads and deletes have been attempted, successful or not, you must call

CompleteAppUploadBatch

. This is indicates indicate to steam that all operation for this batch have been attempt and it will then allow any newly – request batch immediately .

example :

POST https://api.steampowered.com/ICloudService/CompleteAppUploadBatch/v1/ HTTP/1.1
Host: api.steampowered.com
Content-type: application/x-www-form-urlencoded
Content-Length: <body length>

access_token=<token>&input_json={ “appid”: “1234”, “batch_id”: “434565457423”, “batch_eresult”: “1” }

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
batch_id	uint64	✔	TheID number of this batch
batch_eresult	uint32	✔	Result of the batch (see remarks)

The

batch_eresult

parameter should be either 1 (success) or 2 (failure). Technically this is an

EResult

value (see

steam_api.h

for the list). Indicating success or failure to Steam is sufficient for this method.

There’s no body data in the response from this API.

BeginHTTPUpload

Uploading is done via a two-part API. You’ll first call BeginHTTPUpload to get details on where to upload the file, then when that is complete, call CommitHTTPUpload.

example :

POST https://api.steampowered.com/ICloudService/BeginHTTPUpload/v1/ HTTP/1.1
Host: api.steampowered.com
Content-type: application/x-www-form-urlencoded
Content-Length: <body length>

access_token=<token>&input_json={ “appid”: “1234”, “file_size”: “7448889”, “filename”: “%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav”, “file_sha”: “FDFE308499263F9361B472648E9F49DC0B8799C8”, “is_public”: “0”, “platforms_to_sync”: [“all”], “upload_batch_id”: “434565457423”, }

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
file_size	uint32	✔	size of the file in byte
filename	string	✔	the file name
file_sha	string	✔	Hex string (40 digits) representing the SHA1 digest of the file.
platforms_to_sync	string	✔	list of platform for which this file is valid . possible value : All , Windows , MacOS , linux , Android , iphoneo , Switch . case – insensitive .
upload_batch_id	uint64	✔	Thebatch_id return byBeginAppUploadBatch above

Call this API to initiate uploading a new file (or new version of an existing file) to Steam Cloud for the user. New versions of existing file will overwrite the existing version.

Note that for list parameters, such as “platforms_to_sync”, the syntax when used as a GET param is as follows:

&platforms_to_sync[0]=macos&platforms_to_sync[1]=windows

In a JSON-encoded field in a POST param, it is as follows:

” platforms_to_sync ” : [ ” macos ” , ” window ” ]

Theresponse data:

Name	type	description
ugcid	uint64	unique file id (not needed)
timestamp	uint32	epoch timestamp for this change
url_host	string	host FQDN you is upload will upload the file to
url_path	string	path for request . note that currently this include a lead slash character (/) already.
use_https	bool	set to true if you must use HTTPS to perform the upload (generally always true)
request_headers	see below	list of HTTP header you must set on the subsequent PUT request

The”request_headers” list contains this data:

Name	type	description
name	string	the header name
value	string	the header value

To upload the file, make a PUT request to

https://<url_host><url_path>

, where each of the above specified HTTP headers has the specified value. On success you may receive a 200 ok, 201 Created, or 204 No Content response, depending on the storage provider.

This request may look like:

PUT https://steamcloud-us-west1.storage.googleapis.com/00/00/00/00/1234/012_3_4A77D494_9D267_1464.dat?GoogleAccessId=numbersandletters@developer.gserviceaccount.com&Expires=1595961837&Signature=morestuffhere HTTP/1.1
Host: steamcloud-us-west1.storage.googleapis.com
Content-type: application/octet-stream
Content-Length: <body length>
Header-from-Steam1: value1
Header-from-Steam2: value2

<file data>

When that completes (whether a success or a failure), call:

CommitHTTPUpload

example :

POST https://api.steampowered.com/ICloudService/CommitHTTPUpload/v1/ HTTP/1.1
Host: api.steampowered.com
Content-type: application/x-www-form-urlencoded
Content-Length: <body length>

access_token=<token>&input_json={ “appid”: “1234”, “transfer_succeeded”: “1”, “filename”: “%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav”, “file_sha”: “FDFE308499263F9361B472648E9F49DC0B8799C8” }

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
transfer_succeeded	bool	✔	true if the PUT request succeeded
filename	string	✔	the file name
file_sha	string	✔	Hex string (40 digits) representing the SHA1 digest of the file.

Theresponse to this API currently has a single field, “file_committed”, which will be true if Steam was able to fully commit the change. If false, then the upload has failed — a new file was not recorded, and if it was an update to an existing file, the existing file still exists and will be return byfuture Enumerate/Download requests.

delete

example :

POST https://api.steampowered.com/ICloudService/delete/v1/ HTTP/1.1
Host: api.steampowered.com
Content-type: application/x-www-form-urlencoded
Content-Length: <body length>

access_token=<token>&input_json={ “appid”: “1234”, “filename”: “%25WinAppDataLocal%25Foobar%2FGamename%2Fcloud%2Fgames%2Fsave.sav” }

Name	type	require	description
access_token	string	✔	OAuth access token for the user
appid	uint32	✔	Your App ID
filename	string	✔	filename of the file to delete

This API will delete the specified file from the user’s Steam Cloud. Deleting file is permanent; no prior versions of the file are retained. There’s no body data in the response from this API.