diff --git a/content/en-us/projects/assets/api.md b/content/en-us/projects/assets/api.md index 4f4ea7b6c..b73ceff1c 100644 --- a/content/en-us/projects/assets/api.md +++ b/content/en-us/projects/assets/api.md @@ -1,198 +1,318 @@ --- -title: External Catalog Queries -description: External Catalog Queries let you externally query the Creator Store Catalog and Marketplace Catalog. +title: Creator Store Queries +description: Creator Store Queries let you externally query the Creator Store and Marketplace Catalog. --- -You can search Roblox's assets outside Studio by accessing the external catalog API. Use the [Creator Store API](#creator-store-api) to query Studio assets, such as meshes, models, and audio, and the [Marketplace API](#marketplace-api) to query avatar assets on the Marketplace. +You can search Roblox's assets outside Studio by accessing the Creator Store API. Use the [Creator Store API](#creator-store-api) to query Studio assets, such as meshes, models, and audio, and the [Marketplace API](#marketplace-api) to query avatar assets on the Marketplace. Each API requires a URL and custom search parameters for that specific catalog. If both URL and parameters are valid, the API returns a JSON format with the results of your search. ## Creator Store API +> [!NOTE] +> We acknowledge that the toolbox-service API described below is not covered on the official Cloud APIs documentation. We are planning to better support Creator Store search with a cleaner API in future, stay tuned for updates. + + You can query items from the Creator Store catalog using the following URL: -`https://search.roblox.com/catalog/json?[params]` +`https://apis.roblox.com/toolbox-service/v1/marketplace/{categoryId}[params]` + +You can replace `[categoryId]` and `[params]` with the appropriate [query parameters](#query-parameters) to customize your search. + +### CategoryId: + +Valid categoryIds are: + +Audio = 3 +Model = 10 +Decal = 13 +Animation = 24 +Plugin = 38 +MeshPart = 40 +Video = 62 +FontFamily = 73 +Music = 300 + -You can replace `[params]` with the appropriate [query parameters](#query-parameters) to customize your search. ### Query Parameters You can specify search parameters by appending a series of parameters and values to the URL, each separated by a `&`. -Use the following parameters to query the Creator Store catalog: +Use the following parameters to query the Creator Store:
Parameter | -Type | -Options and Values | -
---|---|---|
Category | -byte | -`6` = Models `7` = Plugins `8` = Decals `9` = Audio `10` = Meshes |
-
CreatorID | -long | -Specifies the `Class.Player.UserId|UserID` to filter in the search. If you'd like to find group-created items, enter the group agent's ID, not the group ID. | -
CurrencyType | -byte | -`0` = All (Default) `3` = CustomRobux `5` = Free Use CustomRobux with custom PxMax and PxMin values. |
-
Genres | -byte | -Specifies the genre for the search. The recommended approach to filtering on genres is to match the URL of a catalog page. `1` = TownAndCity `2` = Medieval `3` = SciFi `4` = Fighting `5` = Horror `6` = Naval `7` = Adventure `8` = Sports `9` = Comedy `10` = Western `11` = Military `13` = Building `14` = FPS `15` = RPG |
-
Keyword | -string | -Standard keyword search. | -
PageNumber | -int | -Specifies a page number in conjunction with `ResultsPerPage` to page through results. | -
PxMax | -int | -The maximum price in Robux of items in the query. | -
PxMin | -int | -The minimum price in Robux of items in the query. | -
ResultsPerPage | -int | -By default this is the same as what's currently shown on each catalog browse page. You can't specify a value larger than this maximum amount. | -
SortAggregation | -byte | -`0` = PastDay `1` = PastWeek `2` = PastMonth `3` = AllTime |
-
SortType | -byte | -`0` = Relevance (Default) `1` = MostFavorited `2` = Bestselling `3` = RecentlyUpdated `4` = PriceLowToHigh `5` = PriceHighToLow |
-
Parameter | +Type | +Options and Values | +
categoryId (path) | +int | +
+ Audio = 3 + Model = 10 + Decal = 13 + Animation = 24 + Plugin = 38 + MeshPart = 40 + Video = 62 + FontFamily = 73 + Music = 300 + SoundEffect = 301 + UnknownAudio = 302 + Package = 1001 + SharedPackage = 1002 + |
+
sortOrder | +int | +Asc = 1 Desc = 2 |
+
limit | +int | +Number of results to return, maximum 100. | +
cursor | +string | +Pagination cursor | +
pageNumber | +int | +Page number to request for | +
keyword | +string | +Search keyword | +
assetSubTypes | +array[string] | +Ad, MaterialPack, Package | +
excludeAssetSubTypes | +array[string] | +Ad, MaterialPack, Package | +
creatorType | +int | +1 = User 2 = Group |
+
creatorTargetId | +int64 | +User or Group Id to search for | +
minDuration | +int64 | +Minimum value of the duration range for audio assets in seconds | +
maxDuration | +int64 | +Maximum value of the duration range for audio assets in seconds | +
sortDirection | +int | +None = 0 Ascending = 1 Descending = 2 |
+
artist | +string | +The name of the artist | +
album | +string | +The album you are looking for | +
audioTypes | +array[int] | +Music = 0 SoundEffect = 1 |
+
uiSortIntent | +int | +
+ Relevance = 1 + Trending = 6 + AllTime = 7 + Top = 8 + Duration = 9 + DateCreated = 10 + DateModified = 11 + Creator = 12 + Name = 13 + What sort order to rank the results by + |
+
includeOnlyVerifiedCreators | +bool | +A flag to include only results from verified creators. Verified creators are those that are ID or phone verified. | +
minPriceInCents | +int64 | +Minimum cost in cents (only applicable to plugins) | +
maxPriceInCents | +int64 | +Maximum cost in cents (only applicable to plugins) | +
Field | -Description | -
---|---|
AssetTypeID | -An asset type value. `3` = Audio `4` = Mesh `5` = Lua `10` = Model `13` = Decal `21` = Badge `24` = Animation `34` = GamePass `38` = Plugin `40` = MeshPart |
-
BestPrice | -Empty except for limited edition items, in which case it will return the best price for the item. | -
ContentRatingTypeID | -`0` = No content rating type `1` = 13+ rated item |
-
CreatedDate | -Date the item was created in UTC format. | -
MinimumMembershipLevel | -`1` = Any membership `4` = Roblox Premium only |
-
Name | -Item name in UTF-8 format. | -
PriceView | -This is mostly used by the website to display prices. The options are: `0` = Free `1` = Collectible `2` = HasPrice `3` = NotForSale |
-
PrivateSales | -Empty except for limited edition items, in which case it will return the number of private sellers. | -
UpdatedDate | -Date the item was last updated in UTC format. | -