Search & Querying
The /items and /mice collections accept query parameters for filtering, searching, sorting, pagination, and field selection. A cross-type /search endpoint returns compact, relevance-ranked results, and facet endpoints list the available filter values with counts.
Query parameters
/items, /item, /mice, and /mouse all accept these optional parameters. 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 filters, pagination values, and sort fields return a structured 400 response with an error.code of invalid_query.
Parameters
- Name
qTypestringDescriptionCase-insensitive partial search across name, type, abbreviated name, and description.
searchis accepted as an alias;qis the preferred spelling. - Name
[field]TypestringDescriptionAny top-level field name acts as a case-insensitive exact filter, e.g.
classification=bait,group=Event Mice, or boolean flags likeis_tradable=true. - 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,display_order,id,name, andtype. Mice supportgold,group,id,name,points,subgroup, andtype. - Name
offsetTypeintegerDescriptionNumber of records to skip. Defaults to
0. - Name
limitTypeintegerDescriptionMaximum number of records to return. Unlimited by default.
- Name
metaTypebooleanDescriptionSet to
trueto wrap collection results in{ data, meta }with pagination metadata.
Request
// Tradable cheeses, three at a time, with pagination metadata
const baits = await fetch('https://api.mouse.rip/items?classification=bait&is_tradable=true&fields=id,name&limit=3&meta=true')
console.log(baits)
// Highest-point mice
const mice = await fetch('https://api.mouse.rip/mice?sort=-points&fields=id,name,points&limit=3')
console.log(mice)
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
Search items and mice at once, ranked by relevance. Exact matches rank first, then prefix matches, then partial matches. Results are compact records suited for autocomplete.
Parameters
- Name
qTypestringDescriptionSearch term. Required.
searchis accepted as an alias. - Name
typesTypestringDescriptionRestrict results with
types=itemortypes=mouse. Both are searched by default. - Name
limitTypeintegerDescriptionMaximum results to return. Defaults to
10, maximum50.
Properties
- Name
idTypeintegerDescriptionItem or mouse ID.
- Name
typeTypestringDescriptionItem or mouse type (slug).
- Name
nameTypestringDescriptionItem or mouse name.
- Name
resourceTypestringDescriptionitemormouse. - Name
imageTypestringDescriptionThumbnail image URL, if available.
Request
const results = await fetch('https://api.mouse.rip/search?q=snow&limit=3')
console.log(results)
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"
},
...
],
"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. Useful for building filter UIs on top of the query parameters.
Properties
- Name
facetsTypeobjectDescriptionKeyed by facet name. Each value is an array of
{ count, value }pairs, sorted by count. - Name
metaTypeobjectDescriptionContains
total, the number of items in the dataset.
Request
const facets = await fetch('https://api.mouse.rip/items/facets')
console.log(facets)
Response
{
"facets": {
"classification": [
{ "count": 1392, "value": "convertible" },
{ "count": 524, "value": "stat" },
...
],
"is_tradable": [
{ "count": 3090, "value": "false" },
{ "count": 992, "value": "true" }
],
"tags": [
{ "count": 1392, "value": "convertible" },
...
]
},
"meta": { "total": 4082 }
}
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
metaTypeobjectDescriptionContains
total, the number of mice in the dataset.
Request
const facets = await fetch('https://api.mouse.rip/mice/facets')
console.log(facets)
Response
{
"facets": {
"group": [
{ "count": 170, "value": "Event Mice" },
{ "count": 79, "value": "Rift Walkers" },
...
],
"subgroup": [
{ "count": 62, "value": "Great Winter Hunt" },
...
],
"weakness": [
{ "count": 390, "value": "hydro" },
{ "count": 341, "value": "arcane" },
...
]
},
"meta": { "total": 1311 }
}