External Catalog Queries

You can search Roblox's assets outside Studio by accessing the external Catalog API. Use the Library Catalog API to query Studio assets, such as meshes, models, or audio and the Avatar Catalog API to query Avatar catalog items.

Each API requires a URL and your 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.

Library Catalog API

You can query items from the Library Catalog using the following URL: https://search.roblox.com/catalog/json?[params]

You can replace [params] with the appropriate 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 Studio Asset Library:

Parameter Type Options and Values
Category byte 6 = Models
7 = Plugins
8 = Decals
9 = Audio
10 = Meshes
CreatorID long Specifies the 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

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

Response Fields

API responses return in a JSON format. The response provides asset details with the following primary fields:

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 0 = 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.

The following is an example of expected return output for a single item:


1{
2 "AssetId": 3374795585,
3 "Name": "Rat",
4 "Description": "",
5 "AbsoluteUrl": "https://www.roblox.com/catalog/3374795585/Rat",
6 "Price": "",
7 "Updated": "8 months ago",
8 "Favorited": "80 times",
9 "Sales": "1,613",
10 "Remaining": "",
11 "Creator": "ROBLOX",
12 "CreatorAbsoluteUrl": "https://www.roblox.com/users/1/profile",
13 "PrivateSales": "",
14 "PriceView": 0,
15 "BestPrice": "",
16 "ContentRatingTypeID": 0,
17 "IsServerSideThumbnailLookupInCatalogEnabled": true,
18 "AudioUrl": null,
19 "IsLargeItem": false,
20 "IsThumbnailFinal": true,
21 "IsThumbnailUnapproved": false,
22 "ThumbnailUrl": "https://t1.rbxcdn.com/745a4be8c2366db2e55d0a67678434dc",
23 "BcOverlayUrl": null,
24 "LimitedOverlayUrl": null,
25 "DeadlineOverlayUrl": null,
26 "LimitedAltText": null,
27 "NewOverlayUrl": null,
28 "SaleOverlayUrl": null,
29 "IosOverlayUrl": null,
30 "XboxOverlayUrl": null,
31 "GooglePlayOverlayUrl": null,
32 "AmazonOverlayUrl": null,
33 "IsTransparentBackground": false,
34 "IsNewRobuxIconEnabled": true,
35 "AssetTypeID": 10,
36 "CreatorID": 1,
37 "CreatedDate": "/Date(1561635090927)/",
38 "UpdatedDate": "/Date(1562003916210)/",
39 "IsForSale": false,
40 "IsPublicDomain": true,
41 "IsLimited": false,
42 "IsLimitedUnique": false,
43 "MinimumMembershipLevel": 0,
44 "OffSaleDeadline": null,
45 "ProductId": 586905093
46}
47

Avatar Catalog API

You can query items from the Avatar Catalog using the following URL: https://catalog.roblox.com/v1/search/items/details?[params]

You can replace [params] with the appropriate 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 Avatar Catalog:

Parameter Type Options and Values
Category byte 0 = Featured
1 = All
2 = Collectibles
3 = Clothing
4 = BodyParts
5 = Gear
11 = Accessories
12 = AvatarAnimations
13 = CommunityCreations.
CreatorName string Search by creator name. If CreatorType is not provided, search is for users only.
CreatorTargetId long The user or group ID depending on the CreatorType provided.
CreatorType byte 1 = User or 2 = Group.
Cursor string Each search response contains a nextPageCursor if there is a next page and previousPageCursor if there is a previous page. Pass either of these values in the Cursor parameter of your next query to get the next or previous page of results. The cursor is valid if the other query parameters remain the same.
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.
Limit int Number of results to return. Values are currently limited to 10, 28, and 30.
MaxPrice int The maximum price in Robux of items in the query.
MinPrice int The minimum price in Robux of items in the query.
SortAggregation byte 1 = PastDay
3 = PastWeek
4 = PastMonth
5 = AllTime.
SortType byte 0 = Relevance (Default)
1 = Favorited
2 = Sales
3 = Updated
4 = PriceAsc
5 = PriceDesc.
Subcategory byte 0 = Featured
1 = All
2 = Collectibles
3 = Clothing
4 = BodyParts
5 = Gear
9 = Hats
10 = Faces
12 = Shirts
13 = TShirts
14 = Pants
15 = Heads
19 = Accessories
20 = HairAccessories
21 = FaceAccessories
22 = NeckAccessories
23 = ShoulderAccessories
24 = FrontAccessories
25 = BackAccessories
26 = WaistAccessories
27 = AvatarAnimations
37 = Bundles
38 = AnimationBundles, and
39 = EmoteAnimations
40 = CommunityCreations
41 = Melee
42 = Ranged
43 = Explosive
44 = PowerUp
45 = Navigation
46 = Musical
47 = Social
48 = Building, and
49 = Transport

The following URL will search for the first 10 "Gear" items sorted by all-time ("SortAggregation") and relevance ("SortType") created by Roblox ("CreatorTargetID"):

https://catalog.roblox.com/v1/search/items/details?Subcategory=5&CreatorTargetId=1&SortType=0&SortAggregation=5&Limit=10

Response Fields

API responses return in a JSON format. The response provides asset details in the data key using the following fields:

Field Description
assetType One of the following asset type values (only returned if the item is an asset).
2 = T-Shirt
8 = Hat
11 = Shirt
12 = Pants
17 = Head
18 = Face
19 = Gear
25 = Arms
26 = Legs
27 = Torso
28 = RightArm
29 = LeftArm
30 = LeftLeg
31 = RightLeg
41 = HairAccessory
42 = FaceAccessory
43 = NeckAccessory
44 = ShoulderAccessory
45 = FrontAccessory
46 = BackAccessory
47 = WaistAccessory
48 = ClimbAnimation
49 = DeathAnimation
50 = FallAnimation
51 = IdleAnimation
52 = JumpAnimation
53 = RunAnimation
54 = SwimAnimation
55 = WalkAnimation
56 = PoseAnimation
61 = EmoteAnimation
bundleType The bundle type ID (only returned if the item is a bundle). Possible values are BodyParts and AvatarAnimations.
creatorName The creator's name.
creatorTargetId The creator's ID.
creatorType The item's creator type.
description The item description.
favoriteCount The favorite count of an item.
genres List of the item's genres. Possible values include All, Tutorial, Scary, TownAndCity, War, Funny, Fantasy, Adventure, SciFi, Pirate, FPS, RPG, Sports, Ninja, and WildWest.
id The ID of the item.
itemRestrictions List of the item's restrictions. Possible values include ThirteenPlus, LimitedUnique, Limited, and Rthro.
itemStatus List of the item's status flags. Possible values include New, Sale, XboxExclusive, AmazonExclusive, GooglePlayExclusive, IosExclusive, and SaleTimer.
itemType The item type. Possible values are Asset or Bundle.
lowestPrice The lowest reseller price of the item (only returned if the item is resellable).
name The item name.
price The listing price of the item (current price may differ if the item is resellable).
priceStatus The price status of an item that is not on sale. Possible values are Free, OffSale, or NoResellers.
purchaseCount The purchase count of an item.
unitsAvailableForConsumption The unit available for consumption of a limited unique item.

The following is an example of expected return output for a single item:


1{
2 "keyword": null,
3 "previousPageCursor": null,
4 "nextPageCursor": "2_1_c541d05046b5c1c78a5d386b5e302243",
5 "data": [
6 {
7 "id":527373900,
8 "itemType":
9 "Asset",
10 "assetType":42,
11 "name":"Restless Souls Bandana",
12 "description":"This bandana won't help you blend in with ghosts, but at least you'll be stylish.",
13 "productId":41270974,
14 "genres":[
15 "Scary",
16 "Adventure"
17 ],
18 "itemStatus":[],
19 "itemRestrictions":[],
20 "creatorType":"User",
21 "creatorTargetId":1,
22 "creatorName":"Roblox",
23 "price":300,
24 "favoriteCount":15943,
25 "offSaleDeadline":null
26 }
27 ]
28}
29