We’re excited to announce the Open Cloud Universes API is now available as a public beta! Building on our vision to enable creators to automate workflows, this API makes it possible to read and update information about Universes and Places and restart all servers in a universe (this is equivalent to using the “Restart servers for updates” feature on Creator Dashboard). Both API Keys and OAuth are supported.
This release contains two new resources, Universe and Place, as well as five endpoints to interact with them.
To make it easier to understand which endpoints are relevant to your use cases, we chose to put all relevant fields into a single Universe resource. You can update all of them in a single API call, or you can update a subset of them. The Update endpoints also support new Open Cloud functionality, update masks, which make it easier to configure which fields and subfields you want to update.
With this update, you can now automate place and universe updates (e.g. as part of a CD or LiveOps workflow). You can configure:
Server size
Voice chat settings
Private server status
Supported devices
Restart all servers for updates
You can also update the Place and Universe name and description and configure the experience’s social links, which is often needed to accommodate a new update.
In order to use these new endpoints, you must create an API key or OAuth application with the following scopes:
universe:write
universe.place:write
To learn more about Universes API, check out our docs. If you have feedback, please share with us below. You can also join our OAuth 2.0 group here if you would like access to our beta APIs.
This is really a good update. It may not seem like much but this can allow for automation with external tools for both production and development. Good work to those who contributed.
Why is the Restart Servers API done with a {universeId}:restartServers instead of {universeId}/restart-servers or the like? This seems like a weird decision.
Why is a field mask needed instead of partial JSON?
Since you can set Private Server prices, why is there nothing for setting Paid Access prices?
Personally, I would prefer a separate flag for if Private Servers are enabled or not, rather than setting the price to null.
Is there any chance we’ll see endpoints for creating universes and creating places within universes? This would be useful for my workflow.
Short of it is, we have GitHub actions that deploy new copies of our entire experience and it’s places for testing pull requests. I currently use some odd old APIs and worry that they will get removed at any moment.
Additionally, if there is an endpoint for universe/place creation, would it be possible to have the key used extend permissions to write to them? Open Cloud keys are (understandably) quite rigid and take some work to get them working nicely with new universes.
Perhaps a universe can be marked as a “template” and any permissions the key has for it will carry over to copies of it. That would be really nice.
Thanks for the feedback! I’ll give detailed answers to some of these points where I can (also aware I’m skipping some - I’m not the right person to answer everything).
Why is the Restart Servers API done with a {universeId}:restartServers instead of {universeId}/restart-servers or the like? This seems like a weird decision.
In general, we want to have a syntactic distinction between resources/collections and methods in Open Cloud. The standard CRUD methods (GET/POST/PATCH to resources or collections of resources) don’t require this, but we want to make it impossible for custom methods like :restartServers to be confused with (or even collide with) subresources.
In this case you can read “/restart-servers” and recognize that it’s a verb phrase and so probably a method and not a resource or collection, but that’s semantic rather than syntactic.
Why is a field mask needed instead of partial JSON?
This is a convention that we’ve adopted in general in Open Cloud. There are definitely some tradeoffs, and unfortunately I can’t get into all the details on this one, but we think this is the right long-term approach.
Since you can set Private Server prices, why is there nothing for setting Paid Access prices?
This is good feedback. We might have had a good reason for leaving it out, I don’t remember (but some other staff member might), but perhaps it’ll come in the future.
Personally, I would prefer a separate flag for if Private Servers are enabled or not, rather than setting the price to null.
This would potentially result in ambiguous or invalid configurations, like private servers being disabled but having a nonzero price. What does it mean to change the price while leaving private servers disabled? We wanted to make it harder to express states and operations don’t really mean anything. If a price is meaningful if and only if private servers are enabled then it’s redundant to have two fields.
This is a debatable point of API design philosophy, of course, and we certainly could have done it the way you suggest. Just sharing a bit of our thought process.
Short of it is, we have GitHub actions that deploy new copies of our entire experience and it’s places for testing pull requests. I currently use some odd old APIs and worry that they will get removed at any moment.
We do recommend migrating to Open Cloud when possible - that’s where the majority of our future investment and active support for public APIs will be. But we don’t have any plans to suddenly remove anything without sufficient warning, and we don’t want to break people’s workflows.
Thank you for the detailed response! This is very insightful.
After looking more closely at other Open Cloud endpoints, I can see there’s consistency with the methods approach and I better understand the approach. I actually like the distinction now that it’s been pointed out.
Thinking about it a bit more, especially with private server prices being able to be null, I think this makes a bit more sense. Since some JSON converters might exclude null values rather than explicitly specifying null, I think this approach makes sense since I assume it would see the price in the field mask but not in the JSON body, and infer that it’s being set to null.
Unsure if this is one of the purposes behind it or if it even works that way, haven’t tested it yet, but makes sense on paper.
I was mostly thinking of parity with the develop.roblox.com/v2/universes/{id}/configuration endpoint which has allowPrivateServers and privateServerPrice as separate fields. If I’m recalling correctly, if allowPrivateServers is false, privateServerPrice will always be zero.
I think your explanation makes sense though. Open Cloud is far more consistent in approach than prior iterations of Roblox APIs and it’s nice to get a glimpse of the standards in place. I can see this approach being particularly useful if there’s ever a more complex situation than simply private servers being enabled and what their price is.
Absolutely. I do my best to migrate to Open Cloud as soon as an applicable endpoint is available, however some stuff I’m suspecting might still need workarounds if designed without much flexibility.
My understanding is that there is a system in place to determine what should be intended for public use vs internal use which can be unfortunate to deal with, since public use APIs likely wouldn’t have the flexibility that I’d like to have.
For example, after creating a new universe for a pull request, I actually make a request to the API for modifying OC keys to give the key access to the new universe. This pretty clearly breaks the intent behind the key permissions entirely, but is a means to an end to be able to use OC at all because of permissions.
This is why I suggested the template universes where permissions can be extended without needing to modify the key permissions through the internal API. I imagine this structure would provide the flexibility for my use cases without needing to rely on the internal APIs which only authenticate with cookies.
At least with my current approach, it’s sufficient enough and I don’t need to worry about removal, only breaking changes because Roblox doesn’t expect people to be using them… so far so good though!
A quick aside - a public endpoint for sound permissions would be great, since it’d make it easier for external asset management tools (we built one in-house with the Assets endpoint) to grant permissions to sounds properly.
Will we ever get an API that allows developers to get the amount of running servers, along with the players in said servers for certain games without the third party part?
I can’t seem to get restart servers to work. I am doing the http request correctly and it is returning null as expected in the documentation, but the servers don’t actually close / restart.
I am doing the format correctly, in fact I implemented this for MessagingService and it works just fine.
The permissions are all granted in the API key I’m using.
Just a guess, but it might only close outdated servers. Try updating the experience and then call the API, it might work then. It likely uses the same system as “Restart servers for updates” which does that.