{"openapi":"3.1.0","info":{"title":"Smithsonian Open Access (BYOK) API","version":"0.1.0","description":"Smithsonian Open Access (BYOK) lets an AI assistant read your own Smithsonian Open Access data through the Smithsonian Open Access API with a key you supply (api.data.gov API key). Read-only: 5 tools (search_collections, search_by_category, get_record, list_terms, get_stats). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smithsonian.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smithsonian/docs"},"termsOfService":"https://connectorbay.com/byok-smithsonian/terms"},"servers":[{"url":"https://byok-smithsonian.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smithsonian/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_collections":{"post":{"operationId":"search_collections","summary":"Search the Smithsonian Open Access records (objects, specimens, archives) by text and return matching records with title","description":"Search the Smithsonian Open Access records (objects, specimens, archives) by text and return matching records with title, unit, type and descriptive metadata. Use for \"Find Smithsonian objects about Apollo spacesuits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Search text. Supports AND/OR and fielded terms such as topic:Gastropoda or unit_code:NASM.","maxLength":300,"title":"Q","type":"string"},"row_group":{"anyOf":[{"enum":["objects","archives"],"type":"string"},{"type":"null"}],"default":null,"description":"Record group: objects (objects, artifacts, specimens) or archives (archives collection and item records).","title":"Row Group"},"type":{"anyOf":[{"enum":["edanmdm","ead_collection","ead_component","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Record type: edanmdm, ead_collection, ead_component or all.","title":"Type"},"sort":{"anyOf":[{"enum":["id","newest","updated","random"],"type":"string"},{"type":"null"}],"default":null,"description":"Order of results: id, newest (by record timestamp), updated (by last update) or random. Default order is relevance.","title":"Sort"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Row offset to start from, for paging (0 or more).","title":"Start"},"rows":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 50).","title":"Rows"}},"required":["q"],"title":"search_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_by_category":{"post":{"operationId":"search_by_category","summary":"Search Smithsonian Open Access records inside one broad category: art and design, history and culture, or science and te","description":"Search Smithsonian Open Access records inside one broad category: art and design, history and culture, or science and technology. Use for \"Show Smithsonian science and technology records about meteorites\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cat":{"description":"Category to search: art_design, history_culture or science_technology.","enum":["art_design","history_culture","science_technology"],"title":"Cat","type":"string"},"q":{"description":"Search text. Supports AND/OR and fielded terms such as topic:Gastropoda or unit_code:NASM.","maxLength":300,"title":"Q","type":"string"},"sort":{"anyOf":[{"enum":["id","newest","updated","random"],"type":"string"},{"type":"null"}],"default":null,"description":"Order of results: id, newest (by record timestamp), updated (by last update) or random. Default order is relevance.","title":"Sort"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Row offset to start from, for paging (0 or more).","title":"Start"},"rows":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records to return (1 to 50).","title":"Rows"}},"required":["cat","q"],"title":"search_by_categoryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_record":{"post":{"operationId":"get_record","summary":"Get one Smithsonian Open Access record by its id or url value, with the full descriptive metadata. Use for \"Show the Smi","description":"Get one Smithsonian Open Access record by its id or url value, with the full descriptive metadata. Use for \"Show the Smithsonian record edanmdm-nmaahc_2012.36.4ab\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Record id (for example 'edanmdm-nmaahc_2012.36.4ab') or its url value (for example 'edanmdm:nmaahc_2012.36.4ab').","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_recordArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_terms":{"post":{"operationId":"list_terms","summary":"List the controlled terms the Smithsonian records use in one category (topics, places, cultures, object types, units and","description":"List the controlled terms the Smithsonian records use in one category (topics, places, cultures, object types, units and others), optionally by prefix, to build searches. Use for \"Which Smithsonian topics start with 'astro'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"Term category: culture, data_source, date, object_type, online_media_type, place, topic or unit_code.","enum":["culture","data_source","date","object_type","online_media_type","place","topic","unit_code"],"title":"Category","type":"string"},"starts_with":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only terms starting with this text.","title":"Starts With"}},"required":["category"],"title":"list_termsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_stats":{"post":{"operationId":"get_stats","summary":"Show counts of CC0 objects and media in the Smithsonian Open Access collections. Use for \"How many CC0 objects does Smit","description":"Show counts of CC0 objects and media in the Smithsonian Open Access collections. Use for \"How many CC0 objects does Smithsonian Open Access have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}