Search & Querying
Every collection accepts query parameters for filtering, searching, sorting, pagination, and field selection. /search returns compact, relevance-ranked results across items, mice, and locations, and the facet endpoints list the available filter values with counts.
Query parameters
Every collection accepts these optional parameters: /items, /mice, /attraction, /environments, /recipes, /store, /titles, /power-types and /scoreboards. The same options work when requesting a single record, such as /items/114. Requests without a query string return the complete, unmodified response.
Filtered collection responses include ETag, X-Result-Count, and X-Total-Count headers and support conditional requests with If-None-Match. Invalid pagination values, unsupported sort fields, more than 50 filters, and more than 100 fields return a 400 with an error.code of invalid_query. Parameters that match no field on any record, such as tracking params or typos, are ignored.
Query parameters
- Name
qTypestringDescriptionCase-insensitive partial search across name, type, abbreviated name, and description.searchis an alias. - Name
[field]TypestringDescriptionAny field acts as a case-insensitive exact filter, e.g.classification=bait,group=Event Mice, or boolean flags likeis_tradable=true. Nested fields use dots, including through lists, e.g.has_stats.power_type=hydrooritems.type=super_brie_cheese; a list matches if any of its values does. For fields only some records have, such as an item'sstatusorcategory, records missing the field are excluded. - Name
idsTypestringDescriptionComma-separated (or repeated) IDs for bulk lookup, e.g.ids=114,3058. - Name
typesTypestringDescriptionComma-separated (or repeated) type slugs for bulk lookup. - Name
fieldsTypestringDescriptionComma-separated fields to return. Nested fields are supported, e.g.fields=id,name,images.thumbnail. - Name
sortTypestringDescriptionSort field; prefix with-for descending. Items supportclassification,id,name,type,has_stats.power,has_stats.power_bonus,has_stats.luck, andhas_stats.attraction_bonus. Mice supportgold,group,id,name,points,subgroup,type, andwisdom. Each other collection lists its sort fields on its page. Records without the field go last in either direction. - Name
offsetTypeintegerDescriptionNumber of records to skip. Defaults to0. - Name
limitTypeintegerDescriptionMaximum number of records to return. Unlimited by default. - Name
metaTypebooleanDescriptionSet totrueto wrap collection results in{ data, meta }with pagination metadata. - Name
vTypestringDescriptionCache-busting version token from [/versions](/versions). Not a filter.
Request
const response = await fetch('https://api.mouse.rip/items?classification=bait&is_tradable=true&fields=id,name&limit=3&meta=true')
Response
{
"data": [
{ "id": 103, "name": "Maki Cheese" },
{ "id": 105, "name": "Moon Cheese" },
{ "id": 108, "name": "Radioactive Blue Cheese" }
],
"meta": {
"count": 3,
"has_more": true,
"limit": 3,
"next_offset": 3,
"offset": 0,
"total": 28
}
}
Search
Searches items, mice, and locations at once. Exact matches (a name, a mouse's short name, or a type) rank first, then items whose abbreviation is the whole query (see /item-abbreviations, so sb finds SUPER|brie+), then prefix matches, then partial matches. A term shared by more than four items names a group (charm, hal), so its items come after the name matches.
Query parameters
- Name
qTypestringDescriptionCase-insensitive partial search term. - Name
typesTypestringDescriptionComma-separated:item,location,mouse. Defaults to all three. - Name
limitTypeintegerDescriptionMaximum number of results, 0 to 50. Defaults to 10.
Properties
- Name
idTypeintegerDescriptionItem or mouse ID, or a location's numeric environment ID. - Name
typeTypestringDescriptionItem or mouse type, or location slug (itsidin/environments). - Name
nameTypestringDescriptionItem, mouse, or location name. - Name
resourceTypestringDescriptionitem,location, ormouse. - Name
imageTypestringDescriptionThumbnail image URL, if available.
Request
const response = await fetch('https://api.mouse.rip/search?q=snow&limit=3')
Response
{
"data": [
{
"id": 2723,
"image": "https://www.mousehuntgame.com/images/items/stats/0b8307dd30eae69e58d818f94181e232.gif",
"name": "Festive Snow Decoration",
"resource": "item",
"type": "snow_festive_decoration_stat_item"
},
{
"id": 2731,
"image": "https://www.mousehuntgame.com/images/items/bases/5d1cf08bdd7bce4b17962868e93ad377.jpg",
"name": "Glowing Golem Guardian Base",
"resource": "item",
"type": "snow_golem_base"
},
...
],
"meta": {
"count": 3,
"limit": 3,
"total": 156
}
}
Get item facets
The available item filter values and how many items match each, covering classification, is_tradable, and tags.
Properties
- Name
facetsTypeobjectDescriptionKeyed by facet name. Each value is an array of{ count, value }pairs, sorted by count. - Name
metaTypeobjectDescriptionContainstotal, the number of records in the collection.
Request
const response = await fetch('https://api.mouse.rip/items/facets')
Response
{
"facets": {
"classification": [
{
"count": 1394,
"value": "convertible"
},
{
"count": 533,
"value": "stat"
},
...
],
"is_tradable": [
{
"count": 3111,
"value": "false"
},
{
"count": 1005,
"value": "true"
}
],
"tags": [
{
"count": 1394,
"value": "convertible"
},
{
"count": 588,
"value": "convertibles"
},
...
]
},
"meta": {
"total": 4116
}
}
Get mouse facets
The available mouse filter values and how many mice match each, covering group, subgroup, and weakness.
Properties
- Name
facetsTypeobjectDescriptionKeyed by facet name. Each value is an array of{ count, value }pairs, sorted by count. - Name
metaTypeobjectDescriptionContainstotal, the number of records in the collection.
Request
const response = await fetch('https://api.mouse.rip/mice/facets')
Response
{
"facets": {
"group": [
{
"count": 170,
"value": "Event Mice"
},
{
"count": 79,
"value": "Rift Walkers"
},
...
],
"subgroup": [
{
"count": 62,
"value": "Great Winter Hunt"
},
{
"count": 37,
"value": "Burroughs Rift"
},
...
],
"weakness": [
{
"count": 390,
"value": "hydro"
},
{
"count": 341,
"value": "arcane"
},
...
]
},
"meta": {
"total": 1311
}
}