Cloud Save Files Admin API

Server (admin) API surface for Unity Cloud Save Files: the endpoints that carry the

environments/{environmentId}

path segment. These endpoints are server-authenticated (Service Account /

unity

JWT) and authorized with RBAC permissions, an entitlement check, and a nested-resource check that the environment belongs to the project. The player-facing API (no environment segment) lives in

files/client-v1-routes.yaml

Download OpenAPI specification:

List Player Files

Retrieves a list of names of all the files currently saved in storage for a player along with size (in bytes), last date modified and current WriteLock. Ordered alphabetically in page sizes of 20.

Authorizations

ServiceAccount (cloud_save.files.list)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: cloud_save.files.list

Path parameters for "List Player Files"

projectId

string

required

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

environmentId

string

required

example: 5v3fb205-d8a2-920f-8013-8c0e814777b3

ID of the environment.

playerId

string

required

example: s1QFdyYFXCC2YBocplKoLstxvQ2r

The player ID supplied by the Authorization service.

Query parameters for "List Player Files"

after

string

The key after which to retrieve the next page of files.

pageSize

integer

The list size of the returned files, defaulted to 20.

HTTP response status codes for "List Player Files":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Forbidden

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "List Player Files":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/cloud-save/v1/files/projects/{projectId}/environments/{environmentId}/players/{playerId}/items"

Response example

{ "results": [ { "key": "save-slot-1.dat", "writeLock": "12345678901234567890", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048 } ], "links": { "next": "string" }}

Get Player File Download URL

Generates a signed URL that will allow the client to download the requested player file for a limited period of time. If successful, an object will be returned containing all necessary information to perform the download.

Authorizations

ServiceAccount (cloud_save.files.read)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: cloud_save.files.read

Path parameters for "Get Player File Download URL"

projectId

string

required

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

environmentId

string

required

example: 5v3fb205-d8a2-920f-8013-8c0e814777b3

ID of the environment.

playerId

string

required

example: s1QFdyYFXCC2YBocplKoLstxvQ2r

The player ID supplied by the Authorization service.

key

string

required

Item key.

HTTP response status codes for "Get Player File Download URL":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Forbidden

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Player File Download URL":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/cloud-save/v1/files/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}"

Response example

{ "signedUrl": "string", "httpMethod": "string", "requiredHeaders": {}}

Delete Player File

Deletes the specified player file. If a WriteLock is provided, the file will only be deleted if it matches the stored WriteLock.

Authorizations

ServiceAccount (cloud_save.files.delete)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: cloud_save.files.delete

Path parameters for "Delete Player File"

projectId

string

required

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

environmentId

string

required

example: 5v3fb205-d8a2-920f-8013-8c0e814777b3

ID of the environment.

playerId

string

required

example: s1QFdyYFXCC2YBocplKoLstxvQ2r

The player ID supplied by the Authorization service.

key

string

required

Item key.

Query parameters for "Delete Player File"

writeLock

string

Enforces conflict checking when deleting an existing file. Omitting this field ignores write conflicts. When present, an error response will be returned if the writeLock in the request does not match the stored writeLock.

HTTP response status codes for "Delete Player File":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Forbidden

Not Found

Conflict

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Delete Player File":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/cloud-save/v1/files/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}"

Response example

{ "type": "string", "title": "string", "status": 0, "requestId": null, "code": 0, "detail": "string", "instance": "string", "details": [ {} ]}

Get Player File Metadata

Retrieves the metadata (size, date last modified and created, key, content type, and current WriteLock) of a single player file.

Authorizations

ServiceAccount (cloud_save.files.read)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: cloud_save.files.read

Path parameters for "Get Player File Metadata"

projectId

string

required

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

environmentId

string

required

example: 5v3fb205-d8a2-920f-8013-8c0e814777b3

ID of the environment.

playerId

string

required

example: s1QFdyYFXCC2YBocplKoLstxvQ2r

The player ID supplied by the Authorization service.

key

string

required

Item key.

HTTP response status codes for "Get Player File Metadata":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Forbidden

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Player File Metadata":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/cloud-save/v1/files/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}/metadata"

Response example

{ "key": "save-slot-1.dat", "writeLock": "12345678901234567890", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048}

Get Players

Retrieves a list of all players that have files saved in storage, ordered alphabetically.

Authorizations

ServiceAccount (cloud_save.files.list)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: cloud_save.files.list

Path parameters for "Get Players"

projectId

string

required

example: 8bdacc33-6eef-4577-beb0-633c86259f5b

ID of the project.

environmentId

string

required

example: 5v3fb205-d8a2-920f-8013-8c0e814777b3

ID of the environment.

Query parameters for "Get Players"

after

string

The player after which to retrieve the next page of players.

pageSize

integer

The list size of the returned players, defaulted to 20.

HTTP response status codes for "Get Players":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Forbidden

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "Get Players":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/cloud-save/v1/files/projects/{projectId}/environments/{environmentId}/players"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "accessClasses": { "default": { "totalSize": 0, "numFiles": 0 } } } ], "links": { "next": "string" }}

Cloud Save Files Admin API

List Player Files

Path parameters for "List Player Files"

projectId

environmentId

playerId

Query parameters for "List Player Files"

after

pageSize

HTTP response status codes for "List Player Files":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

403Forbidden

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "List Player Files":

Request example

Response example

GET/projects/{projectId}/environments/{environmentId}/players/{playerId}/items

Get Player File Download URL

Path parameters for "Get Player File Download URL"

projectId

environmentId

playerId

key

HTTP response status codes for "Get Player File Download URL":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

403Forbidden

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "Get Player File Download URL":

Request example

Response example

GET/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}

Delete Player File

Path parameters for "Delete Player File"

projectId

environmentId

playerId

key

Query parameters for "Delete Player File"

writeLock

HTTP response status codes for "Delete Player File":

204OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

403Forbidden

404Not Found

409Conflict

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "Delete Player File":

Request example

Response example

DELETE/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}

Get Player File Metadata

Path parameters for "Get Player File Metadata"

projectId

environmentId

playerId

key

HTTP response status codes for "Get Player File Metadata":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

403Forbidden

404Not Found

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "Get Player File Metadata":

Request example

Response example

GET/projects/{projectId}/environments/{environmentId}/players/{playerId}/items/{key}/metadata