Standard data stores

This page includes reference documentation for working with standard data stores. For more information on using the API, see Handle API requests for data stores and the usage guide.

Datastores

https://apis.roblox.com/datastores

The following endpoints are available at paths relative to the base URL.

List Data Stores

GET /v1/universes/{universeId}/standard-datastores

Returns a list of an experience's data stores.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
cursor string

Provide to request the next set of data. See Cursors.

limit number

The maximum number of items to return. Each call only reads one partition, so it can return fewer than the given value when running out of objectives on one partition.

prefix string

Provide to return only data stores with this prefix.

Request

curl
curl --include --location --request GET "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "prefix=Player" \

-d "limit=5"

Response

200 - OK
Returns an object
application/json
{

  "datastores": [

    {

      "name": "PlayerInventory",

      "createdTime": "2022-02-18T22:38:59.9244932Z"

    },

    {

      "name": "PlayerExperience",

      "createdTime": "2022-02-18T23:00:10.4773508Z"

    },

    {

      "name": "PlayerWeapons",

      "createdTime": "2022-02-18T23:00:22.3725681Z"

    },

    {

      "name": "PlayerArmor",

      "createdTime": "2022-02-18T22:59:33.8472882Z"

    },

    {

      "name": "PlayerHP",

      "createdTime": "2022-02-18T22:58:47.6904028Z"

    }

  ],

  "nextPageCursor": "..."

}
data array<object>

An array of data stores in the target experience.

nextPageCursor string

Indicates that there is more data available in the requested result set. See Cursors.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • List Datastores

Entries

https://apis.roblox.com/datastores

The following endpoints are available at paths relative to the base URL.

List Entries

GET /v1/universes/{universeId}/standard-datastores/datastore/entries

Returns a list of entry keys within a data store.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

scope string

The value is global by default. See Scopes.

allScopes boolean

Set to true to return keys from all scopes.

prefix string

Provide to return only keys with this prefix.

cursor string

Provide to request the next set of data. See Cursors.

limit number

The maximum number of items to return. Each call only reads one partition, so it can return fewer than the given value when running out of objectives on one partition.

Request

curl
curl --include --location --request GET "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "datastoreName=Coins" \

-d "prefix=" \

-d "limit=5"

Response

200 - OK
Returns an object
application/json
{

  "keys": [

    {

      "key": "269323"

    }

  ],

  "nextPageCursor": "eyJ2ZXJzaW9uIjoxLCJjdXJzb3IiOiIzIyJ9"

}
keys array<string>

An array of entry keys within the target data store.

nextPageCursor string

Indicates that there is more data available in the requested result set. See Cursors.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • List Entry Keys

Get Entry

GET /v1/universes/{universeId}/standard-datastores/datastore/entries/entry

Returns the value and metadata associated with an entry.

Metadata can be found in the response headers like the following:

content-md5: zuYxEhwuySMv0i8CitXImw==

roblox-entry-version: 08D9E6A3F2188CFF.0000000001.08D9E6A3F2188CFF.01

roblox-entry-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-version-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-attributes: { "myAttribute": "myValue" }

roblox-entry-userids: [1, 2, 3]
HeaderDescription
content-md5The base-64 encoded MD5 checksum of the content. See Content-MD5.
roblox-entry-versionThe version of the returned entry.
roblox-entry-created-timeThe time at which the entry was created.
roblox-entry-version-created-timeThe time at which this particular version was created.
roblox-entry-attributesAttributes tagged with the entry. Serialized JSON map object.
roblox-entry-useridsComma-separated list of Roblox user IDs tagged with the entry.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

scope string

The value is global by default. See Scopes.

Request

curl
curl --include --location --request GET "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "datastoreName=Coins" \

-d "entryKey=269323"

Response

200 - OK
Successfully retrieved the entry.
Returns an object

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read Entry

Set Entry

POST /v1/universes/{universeId}/standard-datastores/datastore/entries/entry

Sets the value, metadata and user IDs associated with an entry.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

matchVersion string

Provide to update only if the current version matches this.

exclusiveCreate boolean

Create the entry only if it does not exist.

scope string

The value is global by default. See Scopes.

roblox-entry-attributes string

Attributes to be associated with new version of the entry. Serialized by JSON map objects. If not provided, existing attributes are cleared.

Header
roblox-entry-userids string

Comma-separated list of Roblox user IDs tagged with the entry. If not provided, existing user IDs are cleared.

Header
content-md5 string

The base-64 encoded MD5 checksum of the content. See Content-MD5.

Header

Request

curl
curl --include --location --request POST "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry?datastoreName=Coins&entryKey=269323" \

--header "x-api-key: ${API_KEY}" \

--header "content-md5: IGPBYI1uC6+AJJxC4r5YBA==" \

--header "content-type: application/json" \

--header "roblox-entry-userids: [269323]" \

--header "roblox-entry-attributes: {}" \

--d "value"

Response

200 - OK
Returns an object
version string

The version name of the qualifying entry.

deleted boolean

Indicates whether the entry has been deleted.

contentLength number

The length of the content.

createdTime string

The timestamp of when the version was created in the ISO time format.

objectCreatedTime string

The timestamp of when the data store was created in the ISO time format.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Create Entry

  • Update Entry

Delete Entry

DELETE /v1/universes/{universeId}/standard-datastores/datastore/entries/entry

Marks the entry as deleted by creating a tombstone version. Entries are deleted permanently after 30 days.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

scope string

The value is global by default. See Scopes.

Request

curl
curl --include --location --request DELETE "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "datastoreName=Coins" \

-d "entryKey=269323"

Response

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Delete Entry

Increment Entry

POST /v1/universes/{universeId}/standard-datastores/datastore/entries/entry/increment

Increments the value for an entry by a given amount, or create a new entry with that amount. Returns the entry and metadata.

Metadata can be found in the response headers like the following:

content-md5: zuYxEhwuySMv0i8CitXImw==

roblox-entry-version: 08D9E6A3F2188CFF.0000000001.08D9E6A3F2188CFF.01

roblox-entry-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-version-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-attributes: { "myAttribute": "myValue" }

roblox-entry-userids: [1, 2, 3]
HeaderDescription
content-md5The base-64 encoded MD5 checksum of the content. See Content-MD5.
roblox-entry-versionThe version of the returned entry.
roblox-entry-created-timeThe time at which the entry was created.
roblox-entry-version-created-timeThe time at which this particular version was created.
roblox-entry-attributesAttributes tagged with the entry. Serialized JSON map object.
roblox-entry-useridsComma-separated list of Roblox user IDs tagged with the entry.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

incrementBy number

The amount by which the entry should be incremented, or the starting value if it doesn't exist.

scope string

The value is global by default. See Scopes.

roblox-entry-attributes string

Attributes to be associated with new version of the entry. Serialized by JSON map objects. If not provided, existing attributes are cleared.

Header
roblox-entry-userids string

A comma-separated list of Roblox user IDs that the entry is tagged with. If not provided, existing user IDs are cleared.

Header

Request

curl
curl --include --location --request POST "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry/increment" \

--header "x-api-key: ${API_KEY}" \

--header 'content-length: 0' \

--get \

-d "datastoreName=Coins" \

-d "entryKey=269323" \

-d "incrementBy=3"

Response

200 - OK
Returns the latest version of the entry after it has been incremented.
Returns an object

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Create Entry

  • Update Entry

Get Entry Version

GET /v1/universes/{universeId}/standard-datastores/datastore/entries/entry/versions/version

Returns the value and metadata of a specific version of an entry.

Metadata can be found in the response headers like the following:

content-md5: zuYxEhwuySMv0i8CitXImw==

roblox-entry-version: 08D9E6A3F2188CFF.0000000001.08D9E6A3F2188CFF.01

roblox-entry-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-version-created-time: 2022-02-02T23:30:06.5388799+00:00

roblox-entry-attributes: { "myAttribute": "myValue" }

roblox-entry-userids: [1, 2, 3]
HeaderDescription
content-md5The base-64 encoded MD5 checksum of the content. See Content-MD5.
roblox-entry-versionThe version of the returned entry.
roblox-entry-created-timeThe time at which the entry was created.
roblox-entry-version-created-timeThe time at which this particular version was created.
roblox-entry-attributesAttributes tagged with the entry. Serialized JSON map object.
roblox-entry-useridsComma-separated list of Roblox user IDs tagged with the entry.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

versionId string

The version to inspect.

scope string

The value is global by default. See Scopes.

Request

curl
curl --include --location --request GET "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry/versions/version" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "datastoreName=Coins" \

-d "entryKey=269323" \

-d "versionId=08D9E6A3F2188CFF.0000000003.08D9E6DE485A7680.01"

Response

200 - OK
Successfully retrieved the entry.
Returns an object

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • Read Version

Limits

Per API Key: 5000 requests every 60 seconds per IP Address

List Entry Versions

GET /v1/universes/{universeId}/standard-datastores/datastore/entries/entry/versions

Returns a list of versions for an entry.

Parameters

universeId number

The identifier of the experience with data stores that you want to access. You can copy your experience's Universe ID on the Creator Dashboard.

Path
Required
datastoreName string

The name of the data store.

entryKey string

The key identifying the entry.

scope string

The value is global by default. See Scopes.

cursor string

Provide to request the next set of data (see Cursors).

startTime string

Provide to not include versions earlier than this timestamp.

endTime string

Provide to not include versions later than this timestamp.

sortOrder string

Either Ascending (earlier versions first) or Descending (later versions first).

limit number

The maximum number of items to return. Each call only reads one partition, so it can return fewer than the given value when running out of objectives on one partition.

Request

curl
curl --include --location --request GET "https://apis.roblox.com/datastores/v1/universes/3310576216/standard-datastores/datastore/entries/entry/versions" \

--header "x-api-key: ${API_KEY}" \

--get \

-d "datastoreName=Coins" \

-d "entryKey=269323" \

-d "limit=5"

Response

200 - OK
Returns an object
version string

The version name of the qualifying entry.

deleted boolean

Indicates whether the entry has been deleted.

contentLength number

The length of the content.

createdTime string

The timestamp of when the version was created in the ISO time format.

objectCreatedTime string

The timestamp of when the data store was created in the ISO time format.

Required Permissions

The following API key permissions are required to call this endpoint. For more information on generating proper keys, see Manage API keys.

  • List Versions

Objects

The following objects describe payloads that are accepted or returned. See each individual endpoint for more information on when these objects are used.

DataStore

The data store object with its name and created time.

Attributes

name string

The name of your data store.

createdTime string

The timestamp of when the data store was created in the ISO time format.

EntryVersion

The entry version object returned by the List Entry Versions method.

Attributes

version string

The version name of the qualifying entry.

deleted boolean

Indicates whether the entry has been deleted.

contentLength number

The length of the content.

createdTime string

The timestamp of when the version was created in the ISO time format.

objectCreatedTime string

The timestamp of when the data store was created in the ISO time format.