{"openapi":"3.1.0","info":{"title":"DigitalNZ (BYOK) API","version":"0.1.0","description":"DigitalNZ (BYOK) lets an AI assistant read your own DigitalNZ data through the DigitalNZ API with a key you supply (DigitalNZ API key). Read-only: 9 tools (search_records, search_records_by_category, search_records_by_content_partner, search_records_by_place, search_records_by_year, search_records_by_subject, search_reusable_records, get_record, find_similar_records). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-digitalnz.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-digitalnz/docs"},"termsOfService":"https://connectorbay.com/byok-digitalnz/terms"},"servers":[{"url":"https://byok-digitalnz.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-digitalnz/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_records":{"post":{"operationId":"search_records","summary":"Search DigitalNZ records by search terms; returns title, description, date, content partner, collection, links, categori","description":"Search DigitalNZ records by search terms; returns title, description, date, content partner, collection, links, categories, subjects and rights. Use for \"Find records about the 1931 Hawke's Bay earthquake\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"sort":{"anyOf":[{"enum":["syndication_date","date"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by syndication_date or date; default is relevance.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"asc (oldest first) or desc (newest first), used with sort.","title":"Direction"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"title":"search_recordsArguments","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_records_by_category":{"post":{"operationId":"search_records_by_category","summary":"Search records of one category such as Images, Newspapers, Books, Archives, Audio or Videos. Use for \"Show newspaper rec","description":"Search records of one category such as Images, Newspapers, Books, Archives, Audio or Videos. Use for \"Show newspaper records about elections\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"Record category.","enum":["Newspapers","Images","Books","Articles","Journals","Archives","Audio","Other","Manuscripts","Reference sources","Research papers","Videos","Music Score","Groups","Data","Websites","Sets"],"title":"Category","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["category"],"title":"search_records_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/search_records_by_content_partner":{"post":{"operationId":"search_records_by_content_partner","summary":"Search records supplied by one content partner (library, museum or archive), for example 'Ministry for Culture and Herit","description":"Search records supplied by one content partner (library, museum or archive), for example 'Ministry for Culture and Heritage'. Use for \"What records does the Ministry for Culture and Heritage provide about treaties\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"content_partner":{"description":"Exact content partner name, for example 'Ministry for Culture and Heritage'.","maxLength":150,"title":"Content Partner","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["content_partner"],"title":"search_records_by_content_partnerArguments","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_records_by_place":{"post":{"operationId":"search_records_by_place","summary":"Search records tagged with a place name; wildcards like castle* are allowed. Use for \"Find records about Wainuiomata\".","description":"Search records tagged with a place name; wildcards like castle* are allowed. Use for \"Find records about Wainuiomata\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place":{"description":"Place name, for example 'Wainuiomata' or 'castle*'.","maxLength":100,"title":"Place","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["place"],"title":"search_records_by_placeArguments","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_records_by_year":{"post":{"operationId":"search_records_by_year","summary":"Search records dated in one year or a year range such as [1850 TO 1860]. Use for \"What records exist from 1931\".","description":"Search records dated in one year or a year range such as [1850 TO 1860]. Use for \"What records exist from 1931\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"description":"Year or range, for example '1931' or '[1850 TO 1860]'.","maxLength":40,"title":"Year","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["year"],"title":"search_records_by_yearArguments","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_records_by_subject":{"post":{"operationId":"search_records_by_subject","summary":"Search records that carry one subject heading, for example Weddings or Cats; wildcards like climb* are allowed. Use for ","description":"Search records that carry one subject heading, for example Weddings or Cats; wildcards like climb* are allowed. Use for \"Find records with the subject Weddings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subject":{"description":"Subject heading.","maxLength":100,"title":"Subject","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["subject"],"title":"search_records_by_subjectArguments","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_reusable_records":{"post":{"operationId":"search_reusable_records","summary":"Search records whose usage rights allow sharing, modifying or commercial use. Use for \"Find images I can reuse commercia","description":"Search records whose usage rights allow sharing, modifying or commercial use. Use for \"Find images I can reuse commercially about kiwi birds\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"usage":{"description":"Usage right: Share, Modify, Use commercially, All rights reserved or Unknown.","enum":["Share","Modify","Use commercially","All rights reserved","Unknown"],"title":"Usage","type":"string"},"text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search terms; boolean operators and quoted phrases are supported, for example 'Wainuiomata AND school'.","title":"Text"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page of results, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Records per page (1 to 100).","title":"Per Page"}},"required":["usage"],"title":"search_reusable_recordsArguments","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 DigitalNZ record by its id: title, description, dates, partner, links, categories, subjects and rights. Use for ","description":"Get one DigitalNZ record by its id: title, description, dates, partner, links, categories, subjects and rights. Use for \"Show DigitalNZ record 1788754\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"record_id":{"description":"Numeric record id, for example 1788754.","minimum":1,"title":"Record Id","type":"integer"}},"required":["record_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/find_similar_records":{"post":{"operationId":"find_similar_records","summary":"Find records similar to a given record, compared by title and subject. Use for \"What records are similar to DigitalNZ re","description":"Find records similar to a given record, compared by title and subject. Use for \"What records are similar to DigitalNZ record 1788754\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"record_id":{"description":"Numeric record id, for example 1788754.","minimum":1,"title":"Record Id","type":"integer"},"compare_fields":{"anyOf":[{"enum":["title","subject","title,subject"],"type":"string"},{"type":"null"}],"default":null,"description":"Fields used to judge similarity: title, subject or title,subject.","title":"Compare Fields"}},"required":["record_id"],"title":"find_similar_recordsArguments","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}}}}