Cloud Save API
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
Cloud Save Files is for storing data files (binary, JSON, text, CSV, etc.) against keys. The maximum size for player data is 1 GB across all keys for that player. A player can have data in a single file that is up to 1 GB in size, or use many files that equal to less than 1 GB in total size.
Limits:
- Maximum 255 characters per file name
- Maximum 200 files per player
- Maximum 1 GB in size per player across all files
Rate Limits
The API has rate limiting in place. The endpoints are limited to 600 requests per minute on a per-player basis.
The API responds with a HTTP status code if the rate limit is exceeded.
It will also respond with a header to be used in conjunction with a client's retry logic. The value is the number of seconds until a request for the given player will be accepted.
429Retry-AfterDownload OpenAPI specification:
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
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.
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.
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.
Code samples for "{title}":
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
Code samples for "{title}":
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": [] } }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
Code samples for "{title}":
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" }}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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" } ]}
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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
Code samples for "{title}":
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" }}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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" } ]}
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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
Code samples for "{title}":
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" }}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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" } ]}
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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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" } ]}
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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
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.
Code samples for "{title}":
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
Code samples for "{title}":
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": [] } }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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" } ]}
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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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"}
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
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" ] } ]}
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
Code samples for "{title}":
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" }}
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
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 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
Request body for "{title}"
Media Type:
application/jsonThe 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:
- - Equal
EQ - - Not Equal
NE - - Less Than
LT - - Less Than or Equal
LE - - Greater Than
GT - - Greater Than or Equal
GE
Code samples for "{title}":
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 } } ] } ]}
List Player Files
Retrieves a list of names of all the files currently saved in storage for a player along with size (in bytes), last date modified and current WriteLock.
Ordered alphabetically in page sizes of 20.
Authorizations
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
Code samples for "{title}":
Request example
curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items"
Response example
{ "results": [ { "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048 } ], "links": { "next": "string" }}
Get Player File Download URL
Generates a signed URL that will allow the client to download the requested player file for a limited period of time.
If successful, an object will be returned containing all necessary information to perform the download.
Authorizations
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
Code samples for "{title}":
Request example
curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}"
Response example
{ "signedUrl": "string", "httpMethod": "string", "requiredHeaders": {}}
Get Player File upload URL
Initiates the player file upload process and returns a URL to which the actual file contents can be uploaded.
The type, length and MD5 hash of the file have to be provided up-front.
If successful, an object will be returned containing all necessary information to perform the upload.
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
Request body for "{title}"
Media Type:
application/jsonEnforces 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.
Code samples for "{title}":
Request example
curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "contentType": "string", "contentLength": 0, "contentMd5": "string", "writeLock": "efac747f6fb244569efef962ca9dc30e"}' \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}"
Response example
{ "signedUrl": "string", "httpMethod": "string", "requiredHeaders": {}}
Delete Player File
Deletes the specified player file. If a WriteLock is provided, the file will only be deleted if it matches the stored WriteLock.
Authorizations
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
Code samples for "{title}":
Request example
curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/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" ] } ]}
Get Player File Metadata
Retrieves the metadata (size, date last modified and created, key, content type, and current WriteLock) of a single player file.
Authorizations
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
Code samples for "{title}":
Request example
curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://cloud-save.services.api.unity.com/v1/files/projects/{projectId}/players/{playerId}/items/{key}/metadata"
Response example
{ "key": "EXAMPLE_KEY", "writeLock": "efac747f6fb244569efef962ca9dc30e", "modified": { "date": "2020-04-01T13:07:23Z" }, "created": { "date": "2020-04-01T13:07:23Z" }, "contentType": "text/plain", "size": 2048}