Open Cloud Inventory and Groups API, Plus an Upgraded Doc Site

[dragonknightflies]

[Update] July 26, 2024

@YungAK_365

Hey everyone!

We’ve made an update to the Open Cloud Inventory API mentioned above. Previously for an InventoryItem, we were populating the assetDetails > collectibleDetails > instanceState field only if the limited item was a UGC limited.

We’ve now updated the behavior of the API to return the instanceState regardless of what type of limited item it is! We hope that this will better support your workflows and enable new functionality.

Thanks!

---

Hi Creators,

We are thrilled to announce that User Inventory API and Group Read API are now available to everyone as public beta, allowing you to more efficiently manage your community through item ownership validation, group roles listing, and many more!

To ensure consistent creator experience and future expansion, we have decided to use a new, more comprehensive API standard for all Open Cloud APIs. As a result, we updated the API version number to v2 to reflect new standards being used. Along with this, there are a few improvements and principles we are introducing:

• Resource Oriented Design: The data you access will be defined as different types of resources, which can contain hierarchies and have operations (e.g. read and write) towards them.

• Access Public & Private Data: Roblox platform shares certain information publicly, meaning there is no authentication required to get it. For example, user inventory is public by default but a user can choose to set it as private. Open Cloud APIs respect user privacy settings when responding to requests:

  • If the data is public, you can access it with an API key (with or without permissions) or any valid OAuth2 access token.

  • If the data is private, you can use an API key to access your own data, or get explicit user consent through OAuth2 to access their data.

    • With the inventory API, you can access the user’s private inventory once they grant you the permission through OAuth2.

• Standard Documentation: We updated the Open Cloud reference documentation to follow standard conventions and design, giving you a consistent documentation experience across all Open Cloud v2 resources.

User Inventory API

Many community apps have a critical need to access a user’s inventory and have been using the legacy inventory API as a workaround. However, the API is not intended for public consumption and won’t allow you to access private inventories or validate ownership for multiple items. The new Inventory API in Open Cloud is designed to empower third-party use cases from the beginning.

Here’s a video that shows how the API works:

Following resource oriented design, the API introduces “user inventory item” as a new resource, which you can “list” all or a subset of a user’s inventory using filtering. The API supports all item types in a user’s inventory, including Assets, Badges, Passes, and Private Servers.

Here are a few use cases that could be enabled with the API:

• Show relevant inventory items in your app: the Inventory API will return the ItemID (depends on inventory type, it could be assetId, badgeId, etc.) that you can use to fetch details of each item using APIs like catalog)

• Validate a user owns certain items: you can call the Inventory API by providing a list of item types and IDs, and determine ownership based on whether the return contains the items

• View public inventory: you can use an API key (no permission) to list any user’s inventory that’s public.

Rate limits

• 100 requests/min per API key

• 20 requests/min per OAuth2 token

Check out this tutorial or use the Postman Collection (4.2 KB) to learn more about how to use this API.

Groups Read API

Groups have been an important way for you to engage users. Large groups can reach millions of members, making it challenging for tasks such as accepting new join requests, moderation, and ranking members.

Some creators have been using the legacy Groups API to automate certain workflows. However, the API is not designed to be used by third-party tools (requires you to share cookies) and has heavy rate limiting to prevent abuse. By integrating with API keys and OAuth2.0, the Open Cloud Groups API allows you to securely and smoothly manage your Groups related workflows! As the first step, we are exposing the ability to read Group information.

Here’s a video that shows how the API works:

The Groups API can operate on the following hierarchy of resources for a Group:

The resource contains the following info:

• Group: basic group info such as name, description, member count, creation time, etc.

• Group shout: current shout content and the poster

• Group role: the roles defined in the group, including name, description, rank, member count, etc.

• Group membership: the membership info for a specific user, including userId and role

With the Groups read API, you can do the following:

• Display a Group’s info, including shout, in your app

• Check the roles available in a Group and list the members in that role

• List the groups that one or more users are in with “list groups/-/memberships?filter=”users in …“

• Validate whether a user is in a particular Group or having a particular role in that Group

Since all the exposed Group information is public, you can use either an API key or a valid OAuth token to get the data. The rate limits depending on the endpoint:

• Get Group & Get Group Shout

  • 150/min per API key

  • 30/min per OAuth2 token

• List Group Memberships & List Group Roles

  • 300/min per API key

  • 90/min per OAuth2 token

Please note group API keys (i.e. keys created under a group) are currently not supported for both of the APIs.

To learn more about the Groups API, check out the API reference or use the
Group API Postman Collection (6.0 KB). The ability to update Groups resources will be supported in the future. Stay tuned!

---

We’re super pumped about the opportunities that can be unlocked with the APIs! Let us know if you have any questions or feedback. All future Open Cloud APIs will be released in the OAuth2.0 beta group first. If you’d like to get early access to the beta version APIs, please apply to the program using this form.

We are looking forward to seeing the cool features you’ll build! Check out our new doc site to get started.


Cheers,
The Roblox Open Cloud Team

[MineJulRBX]

@dragonknightflies

Group role: the roles defined in the group, including name, description, rank, member count, etc.

We can finally read and take use of the description!? I know this is the weirdest part of it all to be excited about, but I’ve so badly wanted to use rank descriptions to hold additional settings that my game can take use of. Sounds like I’ll finally be able to do that now!

[Sonostrano20 (InceptionStrange)]

I would have expected a way to automatically rank the players in the group but apparently this system is not ready yet.

Also what roblox added about group api is a bit useless nothing that you can already do with Groups API , Really disappointing

And at this point we will continue to use Groups API even if it is not designed to do so, what has been done up to now is not very useful for what the groups really needs

Also what is more disappoint is that in the roadmap they announced this:

and this update of the group API, if there aren’t any others, I don’t think it’s really the right way to manage your group in another way

[TheNexusAvenger (Nexus)]

While I am glad the APIs are moving forward… but the group APIs are really underwhelming. For a couple of groups I am part of, we really needed the ability to write to the group (i.e. group roles) to use this for anything. I see that it is stated that updating will be done in the future, which doesn’t give me confidence it will be any time soon considering how long we have waited only to get read APIs.

[Abcreator]

@dragonknightflies

Standard Documentation: We updated the Open Cloud reference documentation to follow standard conventions and design, giving you a consistent documentation experience across all Open Cloud v2 resources.

Can rate limits be clearly identified on this page? I usually end up just trial and erroring the API or finding old announcement posts for that open cloud api just because of how hidden the rate limits appear to be on the documentation site.

[sanstahskeleton (smatthewihweroush)]

A bit underwhelming if anything. I don’t have much to say really. Don’t know too many uses for these.

[Mauio64 (Mauio)]

Hopefully the group write APIs are done soon. I’ve needed a way to automatically rank-up users for a while now (to prevent group abuse that Roblox still has not properly addressed) but there’s still no way to do this that does not require me to host a bot with my personal account using my own cookies.

The read APIs are nice and are a good step forward, but I hope the staff behind this understand that write APIs for groups are important as well (and for some people, far more important).

[Noble_Draconian]

@Sonostrano20

Also what roblox added about group api is a bit useless nothing that you can already do with Groups API , Really disappointing

Wild idea, perhaps read the full announcement post before commenting? They explicitly elaborated on this:

@dragonknightflies

Some creators have been using the legacy Groups API to automate certain workflows. However, the API is not designed to be used by third-party tools (requires you to share cookies) and has heavy rate limiting to prevent abuse.

[kingerman88]

@dragonknightflies

The ability to update Groups resources will be supported in the future. Stay tuned!

Cannot wait! Thanks for the updates on these new Open Cloud APIs!

[bytesleuth]

This update makes it easier for programmers to access data on the platform, increases the reliability of obtaining this data and reduces the rate limits for accessing this data. As someone who has played around with apis, this will help to make the platform into a more robust ecosystem. Thanks Roblox!

[MightyPart (Mighty)]

In case anyone is interested, I have added both the Inventory and Groups APIs to my typescript opencloud wrapper (openblox).

My wrapper is fully typesafe and makes using these 2 APIs easy.

Docs

Openblox Cloud Inventory API Docs
Openblox Cloud Groups API Docs

---

Inventory Example

This example gets a maximum of 3 pages of items from a users inventory (where each page contains no more than 100 items) using an oauth access token.

import { InventoryApi } from "openblox/apis/cloud";
import { Override, Paginate } from "openblox/interfaces";

const Main = async () => {

  const inventoryItemsForUser_paginatedWithOauthAccessToken = Paginate(Override(InventoryApi.inventoryItemsForUser, { oauthToken: "put oauth access token here" }))

  const allInventoryItems = []
  let [ currentPage, maxPages ] = [ 0, 3 ]
  
  for await (const { data:inventoryItems } of inventoryItemsForUser_paginatedWithOauthAccessToken(45348281, 100, {
    privateServers: true,
    gamePasses: true
  })) {
    currentPage++
    allInventoryItems.push(...inventoryItems)
    if (currentPage == maxPages) break
  }

  console.log(allInventoryItems)
};

Main()

[RuizuKun_Dev (Kitsune)]

I expected the new update to give us the ability to actually manage our groups and not just read information

we want to allow players to join groups from in game and for our games to have the capability to accept members, rank members, etc from within game

[Send_Scripts (Scripty)]

And I still can’t auto rank users? Lame, wouldn’t of been as annoying if your login ip change a year ago wouldnt of broken my node js server

[unmiss (Jack)]

This is great. I’m still looking for the following:

• An API that allows us to rank users without a cookie.
• An API that allows us download a place file. Would be useful for CI/CD.

[Dekkonot]

This is perhaps not your area, but is there any ETA on us being able to upload models through Open Cloud endpoints? It’s been weird to have to rely upon legacy API and using cookies to upload models, to say nothing of the security.

[Happywalker]

I see the new APIs have a clearer definition of the cursors (named tokens here) with some actual guarantees in place. Will the Data Stores listing APIs get the same guarantees at some point? It currently is a bit unclear and explicitly tells the format is not defined.

During tests where I tried to inventorize all keys of a big data store, at some point around key number 5240000 the nextPageCursor pointed to a page with keys I already had received from requests earlier, but with then different cursors.
The dataset I have inventorized does not go above ± 5240000 keys (the number of keys existing is definitely above this amount), even after running my code iterating through the nextPageCursors for a couple of consecutive days. And the nextPageCursor never returns as null/undefined/empty string.
If these are bugs with the current endpoints, I’d be happy to open an official report on the forum.

Also ooh, I see a V2 for these new APIs, can we expect datastores/messagingservice to see a V2 with a move to /cloud soon too?

[SPOOK_EXE (spook)]

Hey, messaged some staff on devforums but I don’t know if it was read but i’ll re-post it here:

Finding the UUID of the given API Key secret via Web-points

I’m implementing a method which has the purpose of getting the given API Key’s UUID when the x-api-key is present in the request headers.

I’m using this to verify whether or not a given API key is valid and usable, as if the API request response does not return the UUID of the API key, then the API key is unavailable. Also, having the API Key UUID allows easier editing when given the Roblox Account / Group Account access that hosts the API key.

I have found an alternative way to do it by having access to the api_keys’ owner’s account, and going through the convoluted method of listing all the api keys, reading the secret preview of each api key, and seeing which of those preview secrets has a match with the given key.

Currently, requests do not give the unique id of the API key when the request header is present.

(trying to get this id)

(through sample python code)

[YungAK_365]

Hmm curious about how what your use case is here. Is there a reason why you want to determine if an API Key is valid? If you try to call an Open Cloud API with an invalid key, you will get an explicit error anyways:

[Bulldo344 (LawMixer)]

I’ve been in the OAuth group for months now, and I love the Roblox staff in it, so helpful, every single one of you.

I do want to plug a python library that one of my friends’ made, rblx-open-cloud. If you have any feedback, or concerns, make sure you open up a Github issue about it.