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: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeOptions and Values
Categorybyte`6` = Models
`7` = Plugins
`8` = Decals
`9` = Audio
`10` = Meshes
CreatorIDlongSpecifies 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.
CurrencyTypebyte`0` = All (Default)
`3` = CustomRobux
`5` = Free

Use CustomRobux with custom PxMax and PxMin values.
GenresbyteSpecifies 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
KeywordstringStandard keyword search.
PageNumberintSpecifies a page number in conjunction with `ResultsPerPage` to page through results.
PxMaxintThe maximum price in Robux of items in the query.
PxMinintThe minimum price in Robux of items in the query.
ResultsPerPageintBy 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.
SortAggregationbyte`0` = PastDay
`1` = PastWeek
`2` = PastMonth
`3` = AllTime
SortTypebyte`0` = Relevance (Default)
`1` = MostFavorited
`2` = Bestselling
`3` = RecentlyUpdated
`4` = PriceLowToHigh
`5` = PriceHighToLow
ParameterTypeOptions 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 +
sortOrderintAsc = 1
Desc = 2
limitintNumber of results to return, maximum 100.
cursorstringPagination cursor
pageNumberintPage number to request for
keywordstringSearch keyword
assetSubTypesarray[string]Ad, MaterialPack, Package
excludeAssetSubTypesarray[string]Ad, MaterialPack, Package
creatorTypeint1 = User
2 = Group
creatorTargetIdint64User or Group Id to search for
minDurationint64Minimum value of the duration range for audio assets in seconds
maxDurationint64Maximum value of the duration range for audio assets in seconds
sortDirectionintNone = 0
Ascending = 1
Descending = 2
artiststringThe name of the artist
albumstringThe album you are looking for
audioTypesarray[int]Music = 0
SoundEffect = 1
uiSortIntentint + 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 +
includeOnlyVerifiedCreatorsboolA flag to include only results from verified creators. Verified creators are those that are ID or phone verified.
minPriceInCentsint64Minimum cost in cents (only applicable to plugins)
maxPriceInCentsint64Maximum cost in cents (only applicable to plugins)
-The following URL will search for 10 items in the "Models" subcategory, sorted by most recently updated. -`https://search.roblox.com/catalog/json?Category=6&SortType=3&ResultsPerPage=10` +For more detailed documentation regarding the toolbox-service, please refer to the updated documentation at creator store API. -### Response Fields +This is a sample response from the endpoint: -API responses return in a JSON format. The response provides asset details with the following primary fields: +``` +{ + "totalResults": int, + "filteredKeyword": string, + "spellCheckerResult": { + "correctionState": int, + "correctedQuery": string, + "userQuery": string + }, + "queryFacets": { + "appliedFacets": Array[string], + "availableFacets": Array[string] + }, + "imageSearchStatus": int, + "previousPageCursor": string, + "nextPageCursor": string, + "data": [ + { + "id": int, + "name": string, + "searchResultSource": string + } + ] +} +``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
AssetTypeIDAn asset type value.
`3` = Audio
`4` = Mesh
`5` = Lua
`10` = Model
`13` = Decal
`21` = Badge
`24` = Animation
`34` = GamePass
`38` = Plugin
`40` = MeshPart
BestPriceEmpty 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
CreatedDateDate the item was created in UTC format.
MinimumMembershipLevel`1` = Any membership
`4` = Roblox Premium only
NameItem name in UTF-8 format.
PriceViewThis is mostly used by the website to display prices. The options are:
`0` = Free
`1` = Collectible
`2` = HasPrice
`3` = NotForSale
PrivateSalesEmpty except for limited edition items, in which case it will return the number of private sellers.
UpdatedDateDate the item was last updated in UTC format.
+To get back the asset metadata, you would go over the data array and extract the ids, call the GetItemDetails endpoint on toolbox-service like this: -The following is an example of expected return output for a single item: +``` +GET https://apis.roblox.com/toolbox-service/v1/items/details?assetIds={assetId1}%2C{assetId2} +``` -```json +### Response Fields + + +This is the response you should expect to get back from that endpoint: + +``` { - "AssetId": 3374795585, - "Name": "Rat", - "Description": "", - "AbsoluteUrl": "https://www.roblox.com/catalog/3374795585/Rat", - "Price": "", - "Updated": "8 months ago", - "Favorited": "80 times", - "Sales": "1,613", - "Remaining": "", - "Creator": "ROBLOX", - "CreatorAbsoluteUrl": "https://www.roblox.com/users/1/profile", - "PrivateSales": "", - "PriceView": 0, - "BestPrice": "", - "ContentRatingTypeID": 0, - "IsServerSideThumbnailLookupInCatalogEnabled": true, - "AudioUrl": null, - "IsLargeItem": false, - "IsThumbnailFinal": true, - "IsThumbnailUnapproved": false, - "ThumbnailUrl": "https://t1.rbxcdn.com/745a4be8c2366db2e55d0a67678434dc", - "BcOverlayUrl": null, - "LimitedOverlayUrl": null, - "DeadlineOverlayUrl": null, - "LimitedAltText": null, - "NewOverlayUrl": null, - "SaleOverlayUrl": null, - "IosOverlayUrl": null, - "XboxOverlayUrl": null, - "GooglePlayOverlayUrl": null, - "AmazonOverlayUrl": null, - "IsTransparentBackground": false, - "IsNewRobuxIconEnabled": true, - "AssetTypeID": 10, - "CreatorID": 1, - "CreatedDate": "/Date(1561635090927)/", - "UpdatedDate": "/Date(1562003916210)/", - "IsForSale": false, - "IsPublicDomain": true, - "IsLimited": false, - "IsLimitedUnique": false, - "MinimumMembershipLevel": 0, - "OffSaleDeadline": null, - "ProductId": 586905093 + "data": [ + { + "asset": { + "audioDetails": { + "audioType": Array[int], + "artist": string, + "title": string, + "musicAlbum": string, + "musicGenre": string, + "soundEffectCategory": string, + "soundEffectSubcategory": string, + "tags": Array[string] + }, + "id": int64, + "name": string, + "typeId": int, + "assetSubTypes": Array[string], + "assetGenres": Array[string], + "ageGuidelines":{ + "ageGuideline: int, + "blood": { + "realism": int, + "level": int + }, + "violence": { + "intensity": int + }, + "profanity": { + "presence": int + }, + "alcohol": { + "presence": int + }, + "romance": { + "type": int + } + }, + "isEndorsed": bool, + "description": string, + "duration": int, + "hasScripts": bool?, + "createdUtc": string($date-time), + "updatedUtc": string($date-time), + "creatingUniverseId": int64?, + "isAssetHashApproved": bool, + "visibilityStatus": int?, + "socialLinks": [{ + "linkType": int, + "url": string, + "title": string + }] + }, + "creator": { + "id": int64, + "name": string, + "type": int, + "isVerifiedCreator": bool, + "latestGroupUpdaterUserId": int64?, + "latestGroupUpdaterUserName": string + }, + "voting": { + "showVotes": bool, + "upVotes": int64, + "downVotes": int64, + "canVote": bool, + "userVote": bool?, + "hasVoted": bool, + "voteCount": int64, + "upVotePercent": int + }, + "product": { + "productId": int64, + "price": int64?, + "isForSaleOrIsPublicDomain": bool + }, + "fiatProduct": { + "purchasePrice": { + "currencyCode": string, + "quantity": { + "significand": int64, + "exponent": int + } + }, + "published": bool, + "purchasable": bool + } + } + ] } ``` + ## Marketplace API You can query avatar items from the Marketplace using the following URL: