Browse Smithsonian by Category
smithsonian_browse_categoryBrowse Smithsonian objects within one exact category — a single museum (mode "museum"), culture, indexed date term (mode "period"), object type (mode "medium"), or subject term (mode "topic"). The value must be an exact indexed category term, not free text: resolve museum, culture, period, and topic vocabulary with smithsonian_list_terms first (object_type is not enumerable there — harvest it from smithsonian_search_objects results, and treat each casing as its own category, since a harvested object_type covers only the casing it was written in). Returns the category total count, a page of matching objects, and a museum breakdown of that page; page the full category with start and rows. For open-ended or topic discovery, start with smithsonian_search_objects instead.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"mode": "<mode>",
"value": "<value>"
},
"name": "smithsonian_browse_category"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Browse dimension: "museum" (by unit code), "culture" (by culture term), "period" (by indexed date term like "1940s" or "500-1500"), "medium" (by object type like "Paintings"), "topic" (by subject term like "Quilts"). | |
| rows | No | Number of sample objects to return (default 10). A value above 1000 is served at 1000 with a notice. | |
| start | No | Pagination offset — 0-indexed. Page contiguously by advancing start by the number of objects returned; a truncated page names the next start in its notice. | |
| value | Yes | Category value appropriate to the mode. museum: a unit code like "NASM", "SAAM", or "NMNHBIRDS", matched literally and case-sensitively — not a museum name. culture: term, often plural or qualified ("Aztecs", "Plains Indian"). period: an indexed date term — commonly a decade ("1940s", "1860s"), but year ranges ("500-1500"), century terms ("21st century"), and BCE forms ("-2500", "BCE 1000s") are indexed too. medium: object type, usually plural ("Paintings", "Aircraft"). topic: subject term ("Quilts", "Aviation"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, period (date), and topic, call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results. Every mode matches its value exactly and case-sensitively, and for medium that split is load-bearing: casing variants are indexed as SEPARATE categories, each reporting its own total_count ("button" and "Button" are different categories, and neither casing is reliably the larger), so browse the variants of a harvested value rather than assuming one covers the concept. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The page size served: rows as requested, or its cap when rows exceeded it. | |
| mode | No | Browse dimension used for this request (one of "museum", "culture", "period", "medium", "topic"). | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of sample objects returned. | |
| value | No | Category value queried, as provided in the request. | |
| notice | No | Guidance naming the input that retrieves the objects this page omitted. Opens with the page size served when rows exceeded its cap. | |
| sources | No | Where this answer came from. A page served from oa_mirror lists its rows in mirror order, not the live API's, and its notice names the snapshot date. Present only on a server that keeps a mirror. | |
| truncated | No | True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld. | |
| total_count | No | Total number of Smithsonian objects matching this category. | |
| sample_objects | No | The requested page of objects matching the category, in upstream order, or in mirror order when sources names oa_mirror. Empty when start is past the end of the category. | |
| mirror_snapshot | No | Publication time (ISO 8601) of the Open Access snapshot the mirror held; what came from oa_mirror reflects the catalog as of then. Present when part of this answer came from oa_mirror. | |
| museum_breakdown | No | When mode is not "museum": top contributing museums from the sample, helping plan museum-focused follow-up searches. | |
| truncationCeiling | No | Total matching objects (upper bound for omitted items). |