Documentation

Cloud Save Data Client API

Cloud Save Data Client API

Cloud Save Data

Introduction

This is the API specification for the Unity Cloud Save service that allows player or custom non-player state to be accessed and persisted from a game client. The Player State API allows data to be stored against a specific player ID. Access using client authentication is limited to the specified player for both data reads and writes. The Game State API allows data to be stored against a custom ID provided by the user. All players are able to read the data from the custom ID using client authentication, but write operations are limited to Service Account authentication. To use this API, you must first enable it through the Unity Gaming Services dashboard.

General Information

Cloud Save Data is for storing small blobs of JSON serializable data, stored as key/value pairs. It can store data against a player ID (referred to as Player State) or a custom ID (referred to as Game State). The custom ID is a string that can be used to store data against a non-player entity, but the client API is restricted to read-only access. In addition to the default access levels for player and game state, data can be stored in public player state, protected player state, or private game state. The access details are as follows:
  • Default Player State: Player-writable and player-readable, by the player the data corresponds to
  • Public Player State: Player-writable by the player the data corresponds to, and readable by any player (e.g. public player profile data)
  • Protected Player State: Server-writable only, and player-readable by the player the data corresponds to
  • Default Game State: Server-writable only, player-readable by any player
  • Private Game State: Server-writable and server-readable only
The maximum size for player or custom data is 5 MB across all key/value pairs for that player and access class. A player can have data in a single slot that is up to 5 MB in size, or use many slots that equal to less than 5 MB in total size. Limits:
  • Maximum 255 characters per slot name
  • Maximum 2000 data slots per player or custom ID per access class
  • Maximum 5 MB in size per player or custom ID per access class across all slots

Rate Limits

The API has rate limiting in place. The endpoints are limited to 600 requests per minute on a per-player basis. The query endpoints (paths ending in 
/query
) are additionally subject to a per-project limit of 6000 requests per minute, shared across all callers of a project. As a result, a query request may receive a 
429
due to the per-project limit even when the individual player is within the 600/minute per-player limit. The API responds with a 
429
HTTP status code if a rate limit is exceeded. It will also respond with a 
Retry-After
header to be used in conjunction with a client's retry logic. The value is the number of seconds until the request will be accepted.
Download OpenAPI specification:

Set Player Item Batch Across Access Classes

Set up to 100 data items with key, value and optional writeLock for the given player, across multiple access classes. The values are limited to a maximum size of 5 MB per access level slots for the player. Saved state for each access level for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic per access class, but may succeed on one access class and fail on another. Error responses should identify the affected key operations that failed.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Player Item Batch Across Access Classes"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Player Item Batch Across Access Classes"

Media Type:
application/json

default

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

public

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

protected

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

private

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Player Item Batch Across Access Classes":

Code samples for "Set Player Item Batch Across Access Classes":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "default": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }, "public": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }, "protected": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }, "private": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/all/item-batch"

Response example

{ "results": { "default": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] }, "public": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] }, "protected": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] }, "private": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] } }}

Get Player Items Across Access Classes

Retrieves saved data values for all keys specified, across access classes. Limited to a maximum of 100 keys across all access classes.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Items Across Access Classes"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Get Player Items Across Access Classes"

Media Type:
application/json

default

object
No description

keys

array[string]
List of keys

public

object
No description

keys

array[string]
List of keys

protected

object
No description

keys

array[string]
List of keys

private

object
No description

keys

array[string]
List of keys

HTTP response status codes for "Get Player Items Across Access Classes":

Code samples for "Get Player Items Across Access Classes":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "default": { "keys": [ "EXAMPLE_KEY" ] }, "public": { "keys": [ "EXAMPLE_KEY" ] }, "protected": { "keys": [ "EXAMPLE_KEY" ] }, "private": { "keys": [ "EXAMPLE_KEY" ] }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/all/item-request"

Response example

{ "results": { "default": { "data": [] }, "public": { "data": [] }, "protected": { "data": [] }, "private": { "data": [] } }}

Get Player Items

Retrieves saved data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Player Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Player Items":

Code samples for "Get Player Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Player Item

Set a data item with a given key and value for the specified player. The value is limited to a maximum size of 5 MB across all default access level slots. The entire default access level saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Player Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Player Item":

Code samples for "Set Player Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Player Items

Deletes all default access level data associated with a given player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

HTTP response status codes for "Delete Player Items":

Code samples for "Delete Player Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Player Keys

Gets a paged list of keys for the given player, ordered alphabetically in pages of 100.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Player Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Player Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Player Keys":

Code samples for "Get Player Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Player Item

Deletes a data item by the specified key for the given player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Query parameters for "Delete Player Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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 Item":

Code samples for "Delete Player Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Player Item Batch

Set up to 20 data items with key, value and optional writeLock for the given player. The values are limited to a maximum size of 5 MB across all default access level slots for the player. The entire default access level saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Player Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Player Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Player Item Batch":

Code samples for "Set Player Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Get Public Player Items

Retrieves saved data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20. Accessible by any player for any other player's data.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Public Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Public Player Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Public Player Items":

Code samples for "Get Public Player Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Public Player Item

Set a public data item with a given key and value for the specified player. The value is limited to a maximum size of 5 MB across all public access level slots. The entire public saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The value set will be publicly readable by any player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Public Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Public Player Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Public Player Item":

Code samples for "Set Public Player Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Public Player Items

Deletes all public data associated with a given player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Public Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

HTTP response status codes for "Delete Public Player Items":

Code samples for "Delete Public Player Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Public Player Keys

Gets a paged list of public keys for the given player, ordered alphabetically in pages of 100. Accessible by any player for any other player's data.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Public Player Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Public Player Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Public Player Keys":

Code samples for "Get Public Player Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Public Player Item

Deletes a public data item by the specified key for the given player.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Public Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Query parameters for "Delete Public Player Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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 Public Player Item":

Code samples for "Delete Public Player Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Public Player Item Batch

Set up to 20 public data items with key, value and optional writeLock for the given player. The values are limited to a maximum size of 5 MB across all slots for the player. The entire public saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Public Player Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Public Player Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Public Player Item Batch":

Code samples for "Set Public Player Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/public/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Get Protected Player Items

Retrieves protected save data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Protected Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Protected Player Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Protected Player Items":

Code samples for "Get Protected Player Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Protected Player Item

Set a protected data item with a given key and value for the specified player. The value is limited to a maximum size of 5 MB across all protected access level slots. The entire protected saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Protected Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Protected Player Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Protected Player Item":

Code samples for "Set Protected Player Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Protected Player Items

Deletes all protected data associated with a given player. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Protected Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

HTTP response status codes for "Delete Protected Player Items":

Code samples for "Delete Protected Player Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Protected Player Keys

Gets a paged list of protected keys for the given player, ordered alphabetically in pages of 100.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Protected Player Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Protected Player Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Protected Player Keys":

Code samples for "Get Protected Player Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Protected Player Item

Deletes a protected data item by the specified key for the given player. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Protected Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Query parameters for "Delete Protected Player Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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 Protected Player Item":

Code samples for "Delete Protected Player Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Protected Player Item Batch

Set up to 20 protected data items with key, value and optional writeLock for the given player. The values are limited to a maximum size of 5 MB across all slots for the player. The entire protected saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Protected Player Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Protected Player Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Protected Player Item Batch":

Code samples for "Set Protected Player Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/protected/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Get Private Player Items

Retrieves private save data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Private Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Private Player Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Private Player Items":

Code samples for "Get Private Player Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Private Player Item

Set a private data item with a given key and value for the specified player. The value is limited to a maximum size of 5 MB across all private access level slots. The entire private saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Private Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Private Player Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Private Player Item":

Code samples for "Set Private Player Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Private Player Items

Deletes all private data associated with a given player. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Private Player Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

HTTP response status codes for "Delete Private Player Items":

Code samples for "Delete Private Player Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Private Player Keys

Gets a paged list of private keys for the given player, ordered alphabetically in pages of 100. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Private Player Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Query parameters for "Get Private Player Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Private Player Keys":

Code samples for "Get Private Player Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Private Player Item

Deletes a private data item by the specified key for the given player. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Private Player Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

key

string
required
Item key.

Query parameters for "Delete Private Player Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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. Only accessible via an authenticated server authority.

HTTP response status codes for "Delete Private Player Item":

Code samples for "Delete Private Player Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Private Player Item Batch

Set up to 20 private data items with key, value and optional writeLock for the given player. The values are limited to a maximum size of 5 MB across all slots for the player. The entire private saved state for a player is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Private Player Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

playerId

string
required
example: s1QFdyYFXCC2YBocplKoLstxvQ2r
The player ID supplied by the Authorization service.

Request body for "Set Private Player Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Private Player Item Batch":

Code samples for "Set Private Player Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/{playerId}/private/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Set Custom Item Batch Across Access Classes

Set up to 100 data items with key, value and optional writeLock for the given custom ID, across multiple access classes. The values are limited to a maximum size of 5 MB per access level slots for the custom ID. Saved state for each access level for a custom ID is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic per access class, but may succeed on one access class and fail on another. Error responses should identify the affected key operations that failed.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Custom Item Batch Across Access Classes"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Set Custom Item Batch Across Access Classes"

Media Type:
application/json

default

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

private

object
No description

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Custom Item Batch Across Access Classes":

Code samples for "Set Custom Item Batch Across Access Classes":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "default": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }, "private": { "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ] }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/all/item-batch"

Response example

{ "results": { "default": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] }, "private": { "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ] } }}

Get Custom Items Across Access Classes

Retrieves saved data values for all keys specified, across access classes. Limited to a maximum of 100 keys across all access classes.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Custom Items Across Access Classes"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Get Custom Items Across Access Classes"

Media Type:
application/json

default

object
No description

keys

array[string]
List of keys

private

object
No description

keys

array[string]
List of keys

HTTP response status codes for "Get Custom Items Across Access Classes":

Code samples for "Get Custom Items Across Access Classes":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "default": { "keys": [ "EXAMPLE_KEY" ] }, "private": { "keys": [ "EXAMPLE_KEY" ] }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/all/item-request"

Response example

{ "results": { "default": { "data": [] }, "private": { "data": [] } }}

Get Custom Items

Retrieves saved data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Custom Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Query parameters for "Get Custom Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Custom Items":

Code samples for "Get Custom Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Custom Item

Set a data item with a given key and value for the specified custom ID. The value is limited to a maximum size of 5 MB across all default access level slots. The entire default access level saved state for a custom ID is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Custom Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Set Custom Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Custom Item":

Code samples for "Set Custom Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Custom Items

Deletes all default access level data associated with a given custom ID. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Custom Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

HTTP response status codes for "Delete Custom Items":

Code samples for "Delete Custom Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Custom Keys

Gets a paged list of keys for the given custom ID, ordered alphabetically in pages of 100.
Authorizations
Client
HTTP: Client
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Custom Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Query parameters for "Get Custom Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Custom Keys":

Code samples for "Get Custom Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Custom Item

Deletes a data item by the specified key for the specified custom ID. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Custom Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

key

string
required
Item key.

Query parameters for "Delete Custom Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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 Custom Item":

Code samples for "Delete Custom Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Custom Item Batch

Set up to 20 data items with key, value and optional writeLock against the custom ID. The values are limited to a maximum size of 5 MB across all default access level slots for the custom ID. The entire default access level saved state for a custom ID is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Custom Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Set Custom Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Custom Item Batch":

Code samples for "Set Custom Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Get Private Custom Items

Retrieves private save data values for all keys specified, ordered alphabetically in pages of 20. If no keys are supplied then returns all keys, ordered alphabetically in pages of 20. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Private Custom Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Query parameters for "Get Private Custom Items"

keys

array
The keys to retrieve, in exploded form style, e.g. 
keys=KEY1&keys=KEY2&keys=KEY3
.

after

string
The key after which to retrieve the next page of keys.

HTTP response status codes for "Get Private Custom Items":

Code samples for "Get Private Custom Items":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/items"

Response example

{ "results": [], "links": { "next": "string" }}

Set Private Custom Item

Set a private data item with a given key and value for the specified custom ID. The value is limited to a maximum size of 5 MB across all private access level slots. The entire private saved state for a custom ID is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Private Custom Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Set Private Custom Item"

Media Type:
application/json

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Private Custom Item":

Code samples for "Set Private Custom Item":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" }}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/items"

Response example

{ "writeLock": "efac747f6fb244569efef962ca9dc30e"}

Delete Private Custom Items

Deletes all private data associated with a given custom ID. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Private Custom Items"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

HTTP response status codes for "Delete Private Custom Items":

Code samples for "Delete Private Custom Items":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/items"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Get Private Custom Keys

Gets a paged list of private keys for the given custom ID, ordered alphabetically in pages of 100. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Get Private Custom Keys"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Query parameters for "Get Private Custom Keys"

after

string
Returns the page of results after the key specified.

HTTP response status codes for "Get Private Custom Keys":

Code samples for "Get Private Custom Keys":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/keys"

Response example

{ "results": [ { "key": "KEY1", "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0", "modified": { "date": "2020-02-20T20:20:20Z" } } ], "links": { "next": "string" }}

Delete Private Custom Item

Deletes a private data item by the specified key for the specified custom ID. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Delete Private Custom Item"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

key

string
required
Item key.

Query parameters for "Delete Private Custom Item"

writeLock

string
Enforces conflict checking when deleting an existing data item. 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 Private Custom Item":

Code samples for "Delete Private Custom Item":

Request example

curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/items/{key}"

Response example

{ "type": "problems/basic", "title": "service unavailable", "status": 500, "code": 1000, "detail": "service unavailable", "details": [ { "health": [ "service health ping failed" ] } ]}

Set Private Custom Item Batch

Set up to 20 private data items with key, value and optional writeLock against the custom ID. The values are limited to a maximum size of 5 MB across all private access level slots for the custom ID. The entire private saved state for a custom ID is limited to 2000 keys. Attempting to set a new key beyond this limit will result in an error. The batch set operation is considered atomic and if any of the set key operation fails, the entire operation is failed. Error responses should identify the affected key operations that failed. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer

Path parameters for "Set Private Custom Item Batch"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

customId

string
required
example: my-custom-data-id
The custom data ID specified by the user. Must be between 1 and 64 characters long and contain only alphanumeric characters, underscores, and hyphens.

Request body for "Set Private Custom Item Batch"

Media Type:
application/json

data

array[object]
No description

key

required
The key will be created if it does not exist, provided the item limit of 2000 keys has not been reached for this entity.

value

object
required
Any JSON serializable structure with a maximum size of 5 MB.

writeLock

string
example: efac747f6fb244569efef962ca9dc30e
Enforces conflict checking when updating an existing data item. This field should be omitted when creating a new data item. When updating an existing item, 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. The writeLock is an opaque value: send back the value returned by this API without changing or interpreting it.

HTTP response status codes for "Set Private Custom Item Batch":

Code samples for "Set Private Custom Item Batch":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "key": "ItemKey", "value": { "Health": 87, "Array": [ 23, 12, 123 ], "Object": { "weapon": "Sword", "damage": 3, "durability": 46 }, "writeLock": "7b8920a57912509f6b5cbb183eb7fcb0" } } ]}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/{customId}/private/item-batch"

Response example

{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e" } ]}

Query Default Player Data

Query player data with the default access class. If no index is available to fulfil the query then the query will fail.
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get

Path parameters for "Query Default Player Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Default Player Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Default Player Data":

Code samples for "Query Default Player Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Query Protected Player Data

Query player data with the protected access class. If no index is available to fulfil the query then the query will fail.
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get

Path parameters for "Query Protected Player Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Protected Player Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Protected Player Data":

Code samples for "Query Protected Player Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/protected/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Query Private Player Data

Query player data with the private access class. If no index is available to fulfil the query then the query will fail. Only accessible via an authenticated server authority.
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get

Path parameters for "Query Private Player Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Private Player Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Private Player Data":

Code samples for "Query Private Player Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/private/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Query Public Player Data

Query player data with the public access class. If no index is available to fulfil the query then the query will fail.
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Query Public Player Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Public Player Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Public Player Data":

Code samples for "Query Public Player Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players/public/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Query Default Custom Data

Query custom data with the default access class. If no index is available to fulfil the query then the query will fail
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get
Client
HTTP: Client
HTTP Authorization Scheme: bearer

Path parameters for "Query Default Custom Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Default Custom Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Default Custom Data":

Code samples for "Query Default Custom Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Query Private Custom Data

Query custom data with the private access class. If no index is available to fulfil the query then the query will fail.
Authorizations
ServiceAccount (cloud_save.indexes.get)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.indexes.get

Path parameters for "Query Private Custom Data"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Request body for "Query Private Custom Data"

Media Type:
application/json

fields

array[object]
required
No description

key

string
required
example: EXAMPLE_KEY
Item key

value

object
required
The indexed Cloud Save value

op

string
required
The comparison operator to use for the filter. The specified value is compared to the indexed value (lexicographically for string data, numerically for numerical data) using one of the following operators:
  • EQ
    - Equal
  • NE
    - Not Equal
  • LT
    - Less Than
  • LE
    - Less Than or Equal
  • GT
    - Greater Than
  • GE
    - Greater Than or Equal

asc

boolean
required
Whether the field is sorted in ascending order

returnKeys

array[string]
The keys to return in the response. This can include keys not on the index. If not specified or empty, the data on the results will be empty for any returned entities.

offset

integer
The number of results to skip. Defaults to 0.

limit

integer
The maximum number of results to return. Defaults to 10. Specifying 0 will return the default number of results.

sampleSize

integer
If set, the given number of random items will be chosen from the total query results and returned as a sample. Defaults to null.

HTTP response status codes for "Query Private Custom Data":

Code samples for "Query Private Custom Data":

Request example

curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "fields": [ { "key": "EXAMPLE_KEY", "value": {}, "op": "EQ", "asc": true } ], "returnKeys": [ "EXAMPLE_KEY" ], "offset": 0, "limit": 0, "sampleSize": 0}' \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom/private/query"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "data": [ { "key": "EXAMPLE_KEY", "value": {}, "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": null }, "created": { "date": null } } ] } ]}

Get Players

Retrieves a paginated list of all players which have data set, ordered alphabetically by player ID, with metadata about their stored data.
Authorizations
ServiceAccount (cloud_save.entities.list)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.entities.list

Path parameters for "Get Players"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Query parameters for "Get Players"

start

The player ID to start the page from. If not specified, the first page will be returned.

limit

integer
The maximum number of player data IDs to return. If not specified, the default limit of 20 will be used.

HTTP response status codes for "Get Players":

Code samples for "Get Players":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/players"

Response example

{ "results": [ { "id": "s1QFdyYFXCC2YBocplKoLstxvQ2r", "accessClasses": { "default": { "totalSize": 0, "numKeys": 0 }, "public": { "totalSize": 0, "numKeys": 0 }, "protected": { "totalSize": 0, "numKeys": 0 }, "private": { "totalSize": 0, "numKeys": 0 } } } ], "links": { "next": "string" }}

Get Custom IDs

Get a paginated list of all Game State custom data IDs for a given project and environment.
Authorizations
ServiceAccount (cloud_save.entities.list)
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Required scopes: cloud_save.entities.list

Path parameters for "Get Custom IDs"

projectId

string
required
example: 8bdacc33-6eef-4577-beb0-633c86259f5b
ID of the project.

Query parameters for "Get Custom IDs"

start

The custom data ID to start the page from. If not specified, the first page will be returned.

limit

integer
The maximum number of custom data IDs to return. If not specified, the default limit of 20 will be used.

HTTP response status codes for "Get Custom IDs":

Code samples for "Get Custom IDs":

Request example

curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/data/projects/{projectId}/custom"

Response example

{ "results": [ { "id": "my-custom-data-id", "accessClasses": { "default": { "totalSize": 0, "numKeys": 0 }, "public": { "totalSize": 0, "numKeys": 0 }, "protected": { "totalSize": 0, "numKeys": 0 }, "private": { "totalSize": 0, "numKeys": 0 } } } ], "links": { "next": "string" }}