rblxopencloud

This reference documents the base API key object, Operation objects as well as the exposed function handling requests internally.

`rblxopencloud.ApiKey`

Represents an API key and allows creation of API classes (such as User) without needing to use the API key string all the time.

Parameters:

Name	Type	Description	Default
`api_key`	`str`	Your API key created from Creator Dashboard.	required

The following attributes are only available after calling fetch_info.

Attributes:

Name	Type	Description
`name`	`Optional[str]`	The name of the API key as set in Creator Dashboard.
`enabled`	`Optional[bool]`	Whether the API key is enabled.
`expired`	`Optional[bool]`	Whether the API key is expired.
`expires_at`	`Optional[datetime]`	The expiration date and time of the API key.
`authorized_user`	`Optional[User]`	The user who generated the API key. For group API keys, this will be the user who last generated the key.

`fetch_info()`

Fetches information about the API key.

Returns:

Type	Description
`Self`	The same `ApiKey` instance with fetched information.

`fetch_asset(asset_id)`

Fetches an asset uploaded to Roblox.

Parameters:

Name	Type	Description	Default
`asset_id`	`int`	The ID of the asset to fetch.	required

Returns:

Type	Description
`Asset`	An `Asset` representing the asset.

`fetch_creator_store_product(asset_type, product_id)`

Fetches information about an asset on the creator store.

Parameters:

Name	Type	Description	Default
`asset_type`	`Union[AssetType, str]`	The type of asset the product is.	required
`product_id`	`int`	The ID of the asset to fetch.	required

Returns:

Type	Description
`CreatorStoreProduct`	A `CreatorStoreProduct` representing the asset.

Tip

If the asset type is unknown or other information such as the description is required, use the fetch_asset.

`fetch_toolbox_asset(asset_id)`

Fetches information about an asset in the toolbox.

Requires creator-store-product:read on an API key. OAuth2 authorization is not supported. No authorization is supported (i.e. api_key is None).

Parameters:

Name	Type	Description	Default
`asset_id`	`int`	The ID of the asset to fetch.	required

Returns:

Type	Description
`ToolboxAsset`	The asset information for the toolbox asset.

`search_toolbox(asset_type, query=None, model_subtype=None, excluded_model_subtype=None, creator=None, verified_creators_only=None, descending=None, limit=None, sort_by=None, min_duration_seconds=None, max_duration_seconds=None, artist=None, album=None, include_top_charts=False, included_instance_types=None, min_price=None, max_price=None, category_path=None, music_chart_type=None, facets=None)`

Searches for assets in the toolbox (or, the creator store) with various filters and sorting options.

Requires creator-store-product:read on an API key. OAuth2 authorization is not supported. No authorization is supported (i.e. api_key is None).

Example

Searchs for audio assets in the toolbox with the query "Menu Theme", uploaded by @DistrokidOffical. The results are filtered to only include assets that are free and are between 45 and 60 seconds long. The first result is printed to the console along with how many more results there are.

user = apikey.get_user(7135127272)

for asset, context in apikey.search_toolbox(
    asset_type=rblxopencloud.AssetType.Audio,
    query="Menu Theme",
    creator=user,
    max_price=Money("USD", 0),
    max_duration_seconds=60,
    min_duration_seconds=45,
    limit=1
):
    print(asset, "and", context.total_results - 1, "more...")
>>> "<rblxopencloud.ToolboxAsset asset_id=114376757380093> and 4 more..."

Parameters:

Name	Type	Description	Default
`asset_type`	`AssetType`	The category of the toolbox assets to search. Only `Audio`, `Model`, `Decal`, `Plugin`, `MeshPart`, `Video`, and `FontFamily` are accepted.	required
`query`	`Optional[str]`	The search query.	`None`
`model_subtype`	`Optional[Sequence[ToolboxAssetSubtype]]`	Any model subtypes to filter by. Only applicable if `asset_type` is `Model`.	`None`
`excluded_model_subtype`	`Optional[Sequence[ToolboxAssetSubtype]]`	Any model subtypes to exclude. Only applicable if `asset_type` is `Model`.	`None`
`creator`	`Optional[Union[Group, User]]`	The creator object (either a group or user) to filter by.	`None`
`verified_creators_only`	`Optional[bool]`	Whether to include only verified creators.	`None`
`descending`	`Optional[bool]`	Whether to sort the results in descending order.	`None`
`sort_by`	`Optional[ToolboxSearchSortCategory]`	The category to sort by. Defaults to relevance.	`None`
`min_duration_seconds`	`Optional[int]`	For audio, the minimum duration of the audio in seconds.	`None`
`max_duration_seconds`	`Optional[int]`	For audio, the maximum duration of the audio in seconds.	`None`
`artist`	`Optional[str]`	For audio, the artist of the audio.	`None`
`album`	`Optional[str]`	For audio, the album of the audio.	`None`
`facets`	`Optional[Sequence[str]]`	Additional keywords to query by. `ToolboxSearchContext.available_facets` contains available facets for the search results.	`None`
`include_top_charts`	`Optional[bool]`	For audio, whether to include top charts results.	`False`
`included_instance_types`	`Optional[Sequence[InstanceType]]`	For plugins, the instance types to include.	`None`
`min_price`	`Optional[Money]`	The minimum price of the asset in USD.	`None`
`max_price`	`Optional[Money]`	The maximum price of the asset in USD.	`None`
`category_path`	`Optional[str]`	The category path to filter by. For instance, `3d__props-and-decor`.	`None`
`music_chart_type`	`Optional[MusicChartType]`	For audio, the type of music chart duration to include.	`None`

Yields:

Type	Description
`Iterable[tuple[ToolboxAsset, ToolboxSearchContext]]`	A tuple containing the asset information for each toolbox asset found and the context for the search results page such as total results, facets, and filtered keywords.

`search_saved_assets(asset_type=None, query=None, asset_id=None, descending=None, limit=None, sort_by=None, exclude_owned_assets=None)`

Iterates through the authenticated user's saved assets with various filters and sorting options.

Requires creator-store-save:read on an API key. OAuth2 authorization is not supported.

Example

Iterates through the authenticated user's saved model assets and prints the first one along with when it was saved and how many more results there are. Ordered with highest rated first.

for asset, context in api_key.search_saved_assets(
    asset_type=AssetType.Model,
    sort_by=ToolboxSearchSortCategory.Top,
    descending=True,
    exclude_owned_assets=True,
):
    print(asset, "saved at", asset.saved_at, "and", context.total_results - 1, "more...")
    break
>>> <rblxopencloud.ToolboxAsset asset_id=77975161416102> saved at 2026-02-11 11:01:33.495+00:00 and 67 more...

Parameters:

Name	Type	Description	Default
`asset_type`	`Optional[AssetType]`	The category of the saved assets to search.	`None`
`query`	`Optional[str]`	Keywords to filter by.	`None`
`asset_id`	`Optional[int]`	The ID of the asset to filter by. Can only be present if `asset_type` is also present.	`None`
`descending`	`Optional[bool]`	Whether to sort the results in descending order.	`None`
`limit`	`Optional[int]`	The maximum number of results to return.	`None`
`sort_by`	`Optional[ToolboxSearchSortCategory]`	The category to sort by. Defaults to saved time.	`None`
`exclude_owned_assets`	`Optional[bool]`	Whether to exclude assets the authenticated user owns from the results.	`None`

Yields:

Type	Description
`Iterable[tuple[ToolboxAsset, ToolboxSearchContext]]`	A tuple containing the asset information for each saved toolbox asset found along with `is_owned` and `saved_at`, and the context for the search results - limited to `total_results` for this endpoint.

`save_asset(asset_id, asset_type)`

Saves an asset from the toolbox to the authenticated user's saved assets.

Requires creator-store-save:write on an API key. OAuth2 authorization is not supported.

Parameters:

Name	Type	Description	Default
`asset_id`	`int`	The ID of the asset to save.	required

`unsave_assets(assets)`

Unsaves one or more assets in the toolbox from the authenticated user's saved assets.

Requires creator-store-save:write on an API key. OAuth2 authorization is not supported.

Example

Unsaves a single asset with ID 114376757380093 of type Audio.

count = api_key.unsave_assets((114376757380093, AssetType.Audio))
print("Unsaved", count, "asset!")
>>> "Unsaved 1 asset!"

Unsaves multiple assets with IDs 114376757380093 of type Audio and 14903722621 of type Model:

count = api_key.unsave_assets([
    (114376757380093, AssetType.Audio),
    (14903722621, AssetType.Model)
])
print("Unsaved", count, "assets!")
>>> "Unsaved 2 assets!"

Parameters:

Name	Type	Description	Default
`assets`	`Union[list[tuple[int, AssetType]], tuple[int, AssetType]]`	A list of tuples (or a single tuple) comprising of the asset ID as the first value, and the asset type as the second value to be unsaved.	required

Returns:

Type	Description
`int`	The number of assets successfully unsaved.

`rblxopencloud.Operation`

Bases: Generic[T]

Represents a request to the Roblox API which takes time to complete such as uploading an asset or flushing an experience's memory store.

Attributes:

Name	Type	Description
`is_done`	`bool`	Wether the operations is known to be complete and `wait()` can provide an immedite response.

`fetch_status()`

Fetches the current status of the operation. If it is complete, it returns the expected value, otherwise returns None.

Returns:

Type	Description
`Optional[T]`	The return type as defined by `T`, or `None` if not completed yet.

Raises:

Type	Description
`HttpException`	The request was not successful.

`wait(timeout_seconds=60, interval_seconds=0, interval_exponent=1.3)`

Continuously checks the status of the operation every interval_seconds until complete or after timeout_seconds has passed.

Parameters:

Name	Type	Description	Default
`timeout_seconds`	`Optional[float]`	The number of seconds until the request stops waiting for completion. Can be `None` to wait forever but not recommended.	`60`
`interval_seconds`	`float`	The number of seconds (excluding network time) between every status check.	`0`
`interval_exponent`	`float`	The number multiplier for exponental backoff. Set to 1 for linear intervals.	`1.3`

Returns:

Type	Description
`T`	The return type as defined by `T`.

Raises:

Type	Description
`HttpException`	The request was not successful.
`TimeoutError`	`timeout_seconds` was exceeded.

`rblxopencloud.send_request(method, path, authorization=None, expected_status=None, retry_max_attempts=2, retry_interval_seconds=1, retry_interval_exponent=2, **kwargs)`

Sends a HTTP request to https://apis.roblox.com and returns the result. It is used internally by the library but can also be used by users for unimplemented apis.

Example

This is an example to send a message with the messaging service API:

status, data, headers = send_request(
    "POST", f"messaging-service/v1/universes/00000000/topics/{topic}",
    authorization="insert-api-key", json={
        "message": "Hello World!"
    }
)

Parameters:

Name	Type	Description	Default
`method`	`str`	The HTTP method to use in uppercase such as `GET` or `POST`.	required
`path`	`str`	The HTTP path of the request, excluding the starting `/`, for example `assets/v1/assets`. Accepts a full URL to request other domains, must start with `http://` or `https://`.	required
`authorization`	`Optional[str]`	The value for the `x-api-key` header. Automatically uses `Authorization` header instead if the value begins with `Bearer`.	`None`
`expected_status`	`Optional[list[int]]`	A list of status codes the function should not handle (such as raise an exception). It is used internally by the library, but can also be used by users to raise errors. Will not raise any errors when `None`.	`None`
`retry_max_attempts`	`int`	The number of retries to complete on an 5xx error. Set to 0 for no retries, defaults to 2.	`2`
`retry_interval_seconds`	`float`	The number of seconds between each retry on a 5xx error. Set to 0 for no delay interval.	`1`
`retry_interval_exponent`	`float`	The second interval exponenet to apply to `retry_interval_seconds` between each attempt.	`2`

Other Parameters:

Name	Type	Description
`params`	`dict[str, Union[str, int, float, bool]]`	A dictionary of query params to send in the request.
`headers`	`dict[str, str]`	A dictionary of headers to include in the request. `user-agent` and `authorization`/`x-api-key` are overwritten.
`json`	`Union[dict, list, str, int, float, bool]`	Any json compatible python object to be sent in the request.
`data`	`(Union[bytes], dict)`	The data to send with the request. Can not be used with `json` parameter.
`timeout`	`float`	The number of seconds until the request times out. Defaults to 15 seconds. Set to `None` for no timeout (not recommended).

Returns:

Type	Description
`tuple[int, Union[str, int, float, dict, list, None], dict]`	A tuple with the first value being the status code, the second value being the response body pre-json decoded if possible, and the last value being the response headers.

Raises:

Type	Description
`HttpException`	HTTP status `400`, `401` 5xx`, or another unepexted status returned which is not in`expected_status`and is not`None`.
`Forbidden`	HTTP status `403` returned when `expected_status` is not `None` and `403` is not in the list.
`NotFound`	HTTP status `401` returned when `expected_status` is not `None` and `401` is not in the list.
`RateLimited`	HTTP status `429` returned when `expected_status` is not `None` and `429` is not in the list.

Note

The send_request function may function slightly differently between the rblxopencloud and rblxopencloudasync modules.