Server definition
- Hash
- sha256:7973d08ba40b36baf464a7b882b47072d83ac35566a9f7ec654bfab6f669e719
- What it is
- What a remote MCP server returned when asked what it offers: 6 tools
The blob, as servednamed by its sha256
{
"instructions": "Smithsonian Open Access API — 14.5M objects across 20+ museums; 5.2M of them carry CC0 media.\nRecommended workflow:\n1. Start with smithsonian_search_objects for free-text or open-ended discovery.\n2. Use smithsonian_list_terms to resolve exact museum (unit_code), culture, place, date, or topic vocabulary — terms are a controlled vocabulary, often plural (e.g. \"Paintings\", not \"Painting\").\n3. Use smithsonian_browse_category to page objects within one known exact category (a single museum, culture, date term, object type, or topic).\n4. Continue with smithsonian_get_object (catalog metadata), smithsonian_get_media (CC0 image URLs), or smithsonian_find_related (cross-collection discovery) by record_id.\n- Requires SMITHSONIAN_API_KEY (free from https://api.data.gov/signup).",
"tools": [
{
"description": "Browse 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"mode": {
"description": "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\").",
"enum": [
"museum",
"culture",
"period",
"medium",
"topic"
],
"type": "string"
},
"rows": {
"default": 10,
"description": "Number of sample objects to return (default 10, max 50).",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"start": {
"default": 0,
"description": "Pagination offset — 0-indexed. Page contiguously with start = page × rows.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"value": {
"description": "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.",
"type": "string"
}
},
"required": [
"mode",
"value"
],
"type": "object"
},
"name": "smithsonian_browse_category",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"mode",
"value",
"total_count",
"sample_objects",
"museum_breakdown"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The rows cap that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_category`: The category value matched no objects — a browse category is an exact indexed facet, so a zero match means the value did not resolve to retrievable objects. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_category"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"mode": {
"description": "Browse dimension used for this request (one of \"museum\", \"culture\", \"period\", \"medium\", \"topic\").",
"type": "string"
},
"museum_breakdown": {
"description": "When mode is not \"museum\": top contributing museums from the sample, helping plan museum-focused follow-up searches.",
"items": {
"additionalProperties": false,
"description": "A single museum contribution entry.",
"properties": {
"count": {
"description": "Estimated object count from sample (not exact).",
"type": "number"
},
"museum_name": {
"description": "Full name of the museum. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code.",
"type": "string"
},
"unit_code": {
"description": "Smithsonian unit code for this museum (e.g. \"NMNHPALEO\", \"SAAM\").",
"type": "string"
}
},
"required": [
"unit_code",
"museum_name",
"count"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance naming the input that retrieves the objects this page omitted.",
"type": "string"
},
"sample_objects": {
"description": "The requested page of objects matching the category, in upstream order. Empty when start is past the end of the category.",
"items": {
"additionalProperties": false,
"description": "A sample object from the requested page of category matches.",
"properties": {
"is_cc0": {
"description": "True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies and cannot gate an image download — read thumbnail_url for that.",
"type": "boolean"
},
"record_id": {
"description": "Object identifier — pass to smithsonian_get_object or smithsonian_get_media.",
"type": "string"
},
"thumbnail_url": {
"description": "Thumbnail image URL if available.",
"type": "string"
},
"title": {
"description": "Object title.",
"type": "string"
},
"unit_code": {
"description": "Museum unit code.",
"type": "string"
}
},
"required": [
"record_id",
"title",
"unit_code",
"is_cc0"
],
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of sample objects returned.",
"type": "number"
},
"total_count": {
"description": "Total number of Smithsonian objects matching this category.",
"type": "number"
},
"truncated": {
"description": "True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
"type": "boolean"
},
"truncationCeiling": {
"description": "Total matching objects (upper bound for omitted items).",
"type": "number"
},
"value": {
"description": "Category value queried, as provided in the request.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Discover objects across Smithsonian collections related to a given anchor object, matched on shared metadata signals — culture, period, object type, named parties, and topic terms. Each related object is tagged with the signals that connected it to the anchor; a named-party signal carries the catalog's own role for that party (maker, Collector, Donor, issuing authority, …), not a fixed \"maker\" label. Matches surface across museums — an NASM aerospace anchor can pull related objects from NMNHPALEO, SAAM, and NMAH.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"id": {
"description": "record_id of the anchor object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object.",
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum number of related objects to return (default 10, max 20).",
"maximum": 20,
"minimum": 1,
"type": "integer"
},
"start": {
"default": 0,
"description": "Pagination offset — 0-indexed. Page contiguously with start = page × limit; each signal is reachable to a depth of 5000 objects, beyond which truncated stays true but deeper pages aren't retrievable.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "smithsonian_find_related",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"anchor",
"related",
"search_signals_used",
"signals"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"anchor": {
"additionalProperties": false,
"description": "Summary of the anchor object used to drive the fan-out searches.",
"properties": {
"record_id": {
"description": "Smithsonian catalog record ID for the input object.",
"type": "string"
},
"title": {
"description": "Title of the input object from the catalog.",
"type": "string"
},
"unit_code": {
"description": "Museum unit code for the input object (e.g. \"NASM\").",
"type": "string"
}
},
"required": [
"record_id",
"title",
"unit_code"
],
"type": "object"
},
"cap": {
"description": "The limit cap that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: The anchor object ID does not exist in the Smithsonian catalog. `invalid_id`: The ID is empty or contains only whitespace. Other values are possible when a failure originates below the handler.",
"examples": [
"not_found",
"invalid_id"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance naming the inputs that retrieve the related objects this page omitted — start for the next page, signals[].search_continuation for a signal past this tool's reach.",
"type": "string"
},
"related": {
"description": "Related objects interleaved across the fan-out signals so each signal contributes. Empty when no related objects were found across all fan-out searches.",
"items": {
"additionalProperties": false,
"description": "A related object with its connecting metadata signals.",
"properties": {
"is_cc0": {
"description": "True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies and cannot gate an image download — read thumbnail_url for that.",
"type": "boolean"
},
"museum_name": {
"description": "Full museum name. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code.",
"type": "string"
},
"record_id": {
"description": "Object identifier — pass to smithsonian_get_object or smithsonian_get_media.",
"type": "string"
},
"similarity_signals": {
"description": "Metadata terms that connected this object to the anchor.",
"items": {
"description": "A metadata signal that connected this object to the anchor (e.g. \"culture: Plains Indian\").",
"type": "string"
},
"type": "array"
},
"thumbnail_url": {
"description": "Thumbnail URL if available.",
"type": "string"
},
"title": {
"description": "Object title.",
"type": "string"
},
"unit_code": {
"description": "Museum unit code.",
"type": "string"
}
},
"required": [
"record_id",
"title",
"unit_code",
"museum_name",
"is_cc0",
"similarity_signals"
],
"type": "object"
},
"type": "array"
},
"search_signals_used": {
"description": "Metadata fields that drove the fan-out searches.",
"items": {
"description": "A metadata signal used for a fan-out search.",
"type": "string"
},
"type": "array"
},
"shown": {
"description": "Number of related objects returned.",
"type": "number"
},
"signals": {
"description": "Per-signal breakdown of every fan-out that returned. Use search_continuation with smithsonian_search_objects to retrieve a signal's matches past this tool's 5000-per-signal reach. A signal whose upstream call failed is omitted.",
"items": {
"additionalProperties": false,
"description": "One fan-out signal with its true size and its retrieval path.",
"properties": {
"row_count": {
"description": "True upstream match count for this signal, uncapped — it can exceed the 5000-per-signal depth this tool's own paging reaches.",
"type": "number"
},
"search_continuation": {
"additionalProperties": false,
"description": "Exact smithsonian_search_objects input that reproduces this signal's full match set, at any depth.",
"properties": {
"filters": {
"additionalProperties": false,
"description": "Pass verbatim as smithsonian_search_objects's filters. Omitted when the signal's constraint is already carried entirely by query.",
"properties": {
"culture": {
"description": "smithsonian_search_objects filters.culture value.",
"type": "string"
},
"date": {
"description": "smithsonian_search_objects filters.date value.",
"type": "string"
},
"name": {
"description": "smithsonian_search_objects filters.name value.",
"type": "string"
},
"object_type": {
"description": "smithsonian_search_objects filters.object_type value.",
"type": "string"
},
"topic": {
"description": "smithsonian_search_objects filters.topic value.",
"type": "string"
}
},
"type": "object"
},
"query": {
"description": "Pass verbatim as smithsonian_search_objects's query. Empty when the signal is expressed entirely through filters.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"signal": {
"description": "Matches an entry in search_signals_used and in related[].similarity_signals.",
"type": "string"
}
},
"required": [
"signal",
"row_count",
"search_continuation"
],
"type": "object"
},
"type": "array"
},
"truncated": {
"description": "True when the related list is incomplete — either capped by the limit or more results exist upstream past the current page (advance start to retrieve them).",
"type": "boolean"
},
"truncationCeiling": {
"description": "Upper bound on the related objects reachable by paging with start. Cross-signal overlaps are not subtracted, so it can overcount. Signals larger than this tool's per-signal reach are counted at that reach — see signals[].row_count for their true size.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Return every CC0 (open-access) image for a Smithsonian object at multiple resolutions. The tool never returns an empty list — it names the reason instead: an object with nothing digitized, an object whose media is entirely non-image (scanned books, 3D models, sound recordings), and an object whose images are entirely non-CC0 each fail with their own reason. Each image entry includes thumbnail (~120px), screen-size (~800px), and high-resolution JPEG/TIFF URLs with pixel dimensions. The cc0_only filter on smithsonian_search_objects surfaces objects that have downloadable CC0 images.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"id": {
"description": "record_id of the object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object.",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "smithsonian_get_media",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"record_id",
"title",
"is_cc0",
"images"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: No object with the given ID exists in the Smithsonian catalog. `no_media`: The object exists but has no digitized online media. `no_images`: The object has digitized media, but none of it is an image — the media is entirely non-image types such as scanned books, 3D models, or sound recordings. `not_cc0`: The object has media but none of its images are CC0 open access. `invalid_id`: The ID is empty or contains only whitespace. Other values are possible when a failure originates below the handler.",
"examples": [
"not_found",
"no_media",
"no_images",
"not_cc0",
"invalid_id"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"images": {
"description": "CC0-licensed images for this object.",
"items": {
"additionalProperties": false,
"description": "A single CC0 image item with resolution variants.",
"properties": {
"alt_text": {
"description": "Accessibility alt text for the image.",
"type": "string"
},
"description": {
"description": "Extended accessibility description.",
"type": "string"
},
"high_res_jpeg": {
"additionalProperties": false,
"description": "Full-resolution JPEG download when available.",
"properties": {
"height": {
"description": "Image height in pixels.",
"type": "number"
},
"url": {
"description": "Direct download URL for the image.",
"type": "string"
},
"width": {
"description": "Image width in pixels.",
"type": "number"
}
},
"required": [
"url"
],
"type": "object"
},
"high_res_tiff": {
"additionalProperties": false,
"description": "Archival TIFF download when available.",
"properties": {
"height": {
"description": "Image height in pixels.",
"type": "number"
},
"url": {
"description": "Direct download URL for the image.",
"type": "string"
},
"width": {
"description": "Image width in pixels.",
"type": "number"
}
},
"required": [
"url"
],
"type": "object"
},
"is_cc0": {
"description": "True when this specific image is CC0 (may differ from the object-level flag). Always true on returned images — non-CC0 images are filtered out before the response.",
"type": "boolean"
},
"media_id": {
"description": "IDS media identifier.",
"type": "string"
},
"screen_url": {
"description": "Screen-size URL (~800px).",
"type": "string"
},
"thumbnail_url": {
"description": "Thumbnail URL (~120px).",
"type": "string"
}
},
"required": [
"media_id",
"is_cc0"
],
"type": "object"
},
"type": "array"
},
"is_cc0": {
"description": "True when the object-level metadata is CC0. The Open Access corpus is CC0 throughout, so this rarely varies; the per-image is_cc0 flag is what gates delivery.",
"type": "boolean"
},
"record_id": {
"description": "Smithsonian catalog record ID for the object.",
"type": "string"
},
"title": {
"description": "Object title from the catalog record.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Fetch a normalized catalog metadata projection for a Smithsonian object by its record_id (from smithsonian_search_objects results). Returns the exposed catalog fields — title, dates, description, makers, materials, dimensions, places, cultures, topics, exhibitions, credit line, identifiers, rights, and a media summary. The media summary is a count; full image URLs come from smithsonian_get_media.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"id": {
"description": "Object record_id from smithsonian_search_objects results (e.g. \"nasm_A19670093000\").",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "smithsonian_get_object",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"record_id",
"title",
"unit_code",
"museum_name",
"dates",
"makers",
"materials",
"dimensions",
"place",
"culture",
"topics",
"exhibitions",
"identifiers",
"is_cc0",
"media_summary"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"credit_line": {
"description": "Attribution or credit string.",
"type": "string"
},
"culture": {
"description": "Culture associations.",
"items": {
"description": "A culture term.",
"type": "string"
},
"type": "array"
},
"dates": {
"description": "All date fields in the catalog record.",
"items": {
"additionalProperties": false,
"description": "A single labeled date entry.",
"properties": {
"label": {
"description": "Date field label (e.g. \"Date\", \"Accession Date\").",
"type": "string"
},
"value": {
"description": "Date value string.",
"type": "string"
}
},
"required": [
"label",
"value"
],
"type": "object"
},
"type": "array"
},
"description": {
"description": "Best available prose description (Summary, Physical Description, or Brief Description notes).",
"type": "string"
},
"dimensions": {
"description": "Dimension and measurement strings.",
"items": {
"description": "A dimension or measurement string.",
"type": "string"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: No object with the given ID exists in the Smithsonian catalog. `invalid_id`: The ID format is clearly malformed (empty string, whitespace only). Other values are possible when a failure originates below the handler.",
"examples": [
"not_found",
"invalid_id"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhibitions": {
"description": "Exhibition history.",
"items": {
"additionalProperties": false,
"description": "A single exhibition entry.",
"properties": {
"building": {
"description": "Building or venue where the exhibition was held.",
"type": "string"
},
"name": {
"description": "Exhibition name.",
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"identifiers": {
"description": "All accession and catalog identifiers.",
"items": {
"additionalProperties": false,
"description": "A single labeled identifier.",
"properties": {
"label": {
"description": "Identifier type (e.g. \"Accession Number\", \"Call Number\").",
"type": "string"
},
"value": {
"description": "Identifier value.",
"type": "string"
}
},
"required": [
"label",
"value"
],
"type": "object"
},
"type": "array"
},
"is_cc0": {
"description": "True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies — read media_summary.has_cc0_images to predict whether smithsonian_get_media returns images.",
"type": "boolean"
},
"makers": {
"description": "All named parties associated with this object.",
"items": {
"additionalProperties": false,
"description": "A single named party entry.",
"properties": {
"name": {
"description": "Name of the party.",
"type": "string"
},
"role": {
"description": "Role of the named party (e.g. \"Artist\", \"Manufacturer\", \"Pilot\").",
"type": "string"
}
},
"required": [
"role",
"name"
],
"type": "object"
},
"type": "array"
},
"materials": {
"description": "Physical material descriptions.",
"items": {
"description": "A material or physical description string.",
"type": "string"
},
"type": "array"
},
"media_summary": {
"additionalProperties": false,
"description": "Media availability summary. Call smithsonian_get_media for full image URLs.",
"properties": {
"cc0_image_count": {
"description": "Number of CC0 images smithsonian_get_media returns for this object. Lower than count when the object has non-image media (e.g. 3D models) or non-CC0 images.",
"type": "number"
},
"count": {
"description": "Total number of online media items, across all types (includes non-image media such as 3D models).",
"type": "number"
},
"has_cc0_images": {
"description": "True when at least one CC0 image is available (cc0_image_count > 0).",
"type": "boolean"
},
"thumbnail_url": {
"description": "Thumbnail URL from the first media item.",
"type": "string"
}
},
"required": [
"count",
"cc0_image_count",
"has_cc0_images"
],
"type": "object"
},
"museum_name": {
"description": "Full museum name. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code.",
"type": "string"
},
"object_rights": {
"description": "Rights statement from the catalog.",
"type": "string"
},
"place": {
"description": "Geographic place associations.",
"items": {
"additionalProperties": false,
"description": "A single labeled place entry.",
"properties": {
"label": {
"description": "Place field label.",
"type": "string"
},
"value": {
"description": "Place name or description.",
"type": "string"
}
},
"required": [
"label",
"value"
],
"type": "object"
},
"type": "array"
},
"record_id": {
"description": "Unique object identifier.",
"type": "string"
},
"record_link": {
"description": "Canonical Smithsonian Institution URL for this object.",
"type": "string"
},
"title": {
"description": "Object title.",
"type": "string"
},
"topics": {
"description": "Subject and topic terms.",
"items": {
"description": "A subject or topic term.",
"type": "string"
},
"type": "array"
},
"unit_code": {
"description": "Museum unit code.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Enumerate the valid term vocabulary for an indexed Smithsonian filter field (unit_code, culture, place, date, online_media_type, topic). Terms are a controlled vocabulary — often plural or qualified (e.g. \"Paintings\", not \"Painting\") — so guessed filter values tend to return nothing. Returns a page of the field's distinct term values; large vocabularies (topic has 133k terms, place 114k) page via start and rows. For unit_code, each code is returned with its museum name and contains matches the name as well as the code, so a museum name resolves to its code in one call.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"contains": {
"description": "Case-insensitive substring filter on the term vocabulary — resolve a filter value (e.g. \"greek\") to its exact controlled-vocabulary term(s). For unit_code the substring also matches each code's museum name, so \"National Air and Space\" resolves to \"NASM\".",
"type": "string"
},
"field": {
"description": "Indexed field to enumerate. Choices: unit_code (museum codes like \"NASM\"), culture (e.g. \"Aztecs\"), place (geographic terms), date (decade/era values like \"1920s\"), online_media_type (media formats like \"Images\", \"3D Models\"), topic (subject terms like \"Quilts\" — 133k terms, so pair it with contains).",
"enum": [
"unit_code",
"culture",
"place",
"date",
"online_media_type",
"topic"
],
"type": "string"
},
"rows": {
"default": 50,
"description": "Number of terms to return per page (default 50, max 100).",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"start": {
"default": 0,
"description": "Pagination offset (0-indexed). Use with rows to page through large vocabularies.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"field"
],
"type": "object"
},
"name": "smithsonian_list_terms",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"field",
"terms",
"total"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The rows cap that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_terms`: The field returned no indexed terms. Other values are possible when a failure originates below the handler.",
"examples": [
"no_terms"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"field": {
"description": "The enumerated field, as provided in the request.",
"type": "string"
},
"labels": {
"additionalProperties": {
"type": "string"
},
"description": "Museum name for each unit_code on this page that has one — present only when field is \"unit_code\". A few rarely-indexed archive sub-unit codes have no mapped name and are absent from this map; their term is still returned in terms.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"notice": {
"description": "Guidance naming the input that retrieves the terms this page omitted, or how to broaden a contains filter that matched nothing.",
"type": "string"
},
"shown": {
"description": "Number of terms returned in this page.",
"type": "number"
},
"terms": {
"description": "The field's distinct term values for this page, in the Smithsonian index's native order. No per-term object counts are available upstream.",
"items": {
"description": "A term value — pass directly as the filter value in smithsonian_search_objects or smithsonian_browse_category.",
"type": "string"
},
"type": "array"
},
"total": {
"description": "Total number of distinct terms for this field (the full vocabulary size; terms is one page of it).",
"type": "number"
},
"truncated": {
"description": "True when matching terms remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
"type": "boolean"
},
"truncationCeiling": {
"description": "Distinct terms available for this query (the full vocabulary, or the contains-match count) — upper bound for omitted items.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Recommended first step for open-ended or topic discovery: free-text search across 14.5 million Smithsonian objects, with optional exact filters. Filters narrow by museum unit, object type, indexed date term, culture, geographic place, subject topic, named party, and online/CC0 availability. Returns curated summaries (title, date, museum, thumbnail URL, CC0 flag) with the total match count. The record_id in each result is the identifier for smithsonian_get_object, smithsonian_find_related, and smithsonian_get_media. To browse one exact category — a single museum, culture, date term, object type, or topic — use smithsonian_browse_category instead.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filters": {
"description": "Optional structured filters to narrow the search.",
"properties": {
"cc0_only": {
"description": "When true, restrict to records that have CC0-licensed media attached (the Lucene term media_usage:CC0). This selects on media presence, not license status — the roughly 9.2M records it excludes are CC0 too, they simply have nothing digitized. Read has_media on each result to decide whether smithsonian_get_media will return anything.",
"type": "boolean"
},
"culture": {
"description": "Culture term from the controlled vocabulary — often plural or qualified (e.g. \"Aztecs\", \"Plains Indian\"). The vocabulary is enumerable via smithsonian_list_terms (field \"culture\").",
"type": "string"
},
"date": {
"description": "Indexed date term. Decades (\"1920s\", \"1960s\") are the most common form, but the vocabulary also carries year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\"). The value must be an exact term — the full set is enumerable via smithsonian_list_terms (field \"date\").",
"type": "string"
},
"name": {
"description": "Indexed named party — maker, collector, donor, issuing authority, or any other role the catalog records. Written surname-first (e.g. \"Warhol, Andy\"). This field is not enumerable via smithsonian_list_terms. A smithsonian_find_related name signal carries the indexed form verbatim and is the reliable source; smithsonian_get_object's makers[] is the catalog's free-text form of the same parties and is often written differently (\"Major J. A. L. Möller (Jacob A.L. Möller/Monty Möller), Non-Indian, 1883-1957\" for the indexed \"Möller, Major J. A. L.\"), so treat it as a starting guess.",
"type": "string"
},
"object_type": {
"description": "Object type term from Smithsonian's controlled vocabulary — commonly plural (e.g. \"Paintings\", \"Photographs\", \"Aircraft\"). Singular everyday forms like \"Painting\" usually return nothing. This field is not enumerable via smithsonian_list_terms; harvest valid values from the object_type field in smithsonian_search_objects results. Matched exactly and case-sensitively, and casing variants are indexed as SEPARATE categories — \"button\" and \"Button\" each hold their own records, and neither casing is reliably the larger — so probe a harvested value's other casings rather than assuming one covers the concept.",
"type": "string"
},
"online_only": {
"description": "When true, restrict to records carrying an indexed online_media_type value. That vocabulary covers digitized surrogates — finding aids, catalog cards, scanned books, full text, electronic resources — alongside images, 3D models, and video, and the surrogate types often have no deliverable media attached, so a match can still report has_media: false. Read has_media on each result to decide whether smithsonian_get_media will return anything.",
"type": "boolean"
},
"place": {
"description": "Geographic place (e.g. \"United States of America\"). The full set is enumerable via smithsonian_list_terms (field \"place\").",
"type": "string"
},
"topic": {
"description": "Subject term from the controlled vocabulary (e.g. \"Quilts\", \"Aviation\"). Matches the topics[] values smithsonian_get_object returns, and is a hard constraint — topic \"Quilts\" matches 1,134 objects where the same word as free text matches 2,677. The full set is enumerable via smithsonian_list_terms (field \"topic\").",
"type": "string"
},
"unit_code": {
"description": "Museum unit code (e.g. \"NASM\", \"SAAM\", \"NMAH\", \"NMAAHC\", \"NMAI\", \"NPG\", \"CHNDM\", \"SIL\"); the National Museum of Natural History is indexed under discipline sub-units like \"NMNHBIRDS\" and \"NMNHPALEO\", not a bare \"NMNH\". The full set is enumerable via smithsonian_list_terms (field \"unit_code\").",
"type": "string"
}
},
"type": "object"
},
"query": {
"description": "Free-text search. Use specific terms for precision (\"Tlingit totem pole\") or broad terms for browsing (\"quilt\").",
"type": "string"
},
"rows": {
"default": 20,
"description": "Page size (default 20, max 100).",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"start": {
"default": 0,
"description": "Pagination offset — 0-indexed. Use with rows for paging through large result sets.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "smithsonian_search_objects",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"objects",
"total_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The rows cap that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_results`: An unfiltered query matched no objects. `invalid_filter`: A filtered search matched nothing — most often a filter value outside the Smithsonian controlled vocabulary (e.g. a singular \"Painting\" instead of \"Paintings\"). Other values are possible when a failure originates below the handler.",
"examples": [
"no_results",
"invalid_filter"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance naming the input that retrieves the objects this page omitted.",
"type": "string"
},
"objects": {
"description": "Curated object summaries for the current page.",
"items": {
"additionalProperties": false,
"description": "Curated summary of a single Smithsonian catalog object.",
"properties": {
"date": {
"description": "Indexed date term for the object — commonly a decade (\"1960s\"), but the vocabulary also carries year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\"). Sparse — omitted when the record has no indexed date.",
"type": "string"
},
"has_media": {
"description": "True when the object carries deliverable online media items. This is the signal smithsonian_get_media reads, so it — not the online_only filter — predicts whether that call returns anything.",
"type": "boolean"
},
"is_cc0": {
"description": "True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies and cannot gate an image download — read has_media for that.",
"type": "boolean"
},
"museum_name": {
"description": "Full museum name for the unit code. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code.",
"type": "string"
},
"object_type": {
"description": "Object type term (e.g. \"Aircraft\", \"Paintings\", \"Photographs\"). Harvest it here to filter a later search, but it is case-sensitive and casing variants are separate categories upstream — this row carries one casing of the concept, not all of it.",
"type": "string"
},
"record_id": {
"description": "Unique object identifier — pass to smithsonian_get_object, smithsonian_get_media, or smithsonian_find_related.",
"type": "string"
},
"thumbnail_url": {
"description": "Thumbnail image URL (~120px) if the object has online media.",
"type": "string"
},
"title": {
"description": "Object title from the catalog.",
"type": "string"
},
"unit_code": {
"description": "Museum unit code (e.g. \"NASM\", \"SAAM\", \"NMNHBIRDS\"). Use as a filter in future searches.",
"type": "string"
}
},
"required": [
"record_id",
"title",
"unit_code",
"museum_name",
"is_cc0",
"has_media"
],
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of objects returned in this page.",
"type": "number"
},
"total_count": {
"description": "Total matching objects in the Smithsonian catalog before pagination.",
"type": "number"
},
"truncated": {
"description": "True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
"type": "boolean"
},
"truncationCeiling": {
"description": "Total matching objects (upper bound for omitted items).",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:7973d08ba40b36baf464a7b882b47072d83ac35566a9f7ec654bfab6f669e719 | sha256sum