{"openapi":"3.1.0","info":{"title":"Digital Public Library of America (BYOK) API","version":"0.1.0","description":"Digital Public Library of America (BYOK) lets an AI assistant read your own Digital Public Library of America data through the Digital Public Library of America API with a key you supply (DPLA API key). Read-only: 6 tools (search_items, search_items_by_date, search_items_in_state, get_item, facet_counts, search_collections). The BYOK key travels with each request, is used for that one call only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-dpla.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-dpla/docs"},"termsOfService":"https://connectorbay.com/byok-dpla/terms"},"servers":[{"url":"https://byok-dpla.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-dpla/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_items":{"post":{"operationId":"search_items","summary":"Search DPLA items (digitized books, photographs, maps, audio, documents) by text and by title, creator, subject, type or","description":"Search DPLA items (digitized books, photographs, maps, audio, documents) by text and by title, creator, subject, type or contributing institution; returns title, creator, date, description, provider and links. Use for \"Find photographs of the 1906 San Francisco earthquake in DPLA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Words to search in all text fields; AND by default, use OR for alternatives, '*' as wildcard, quotes for phrases.","title":"Q"},"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words that must appear in the item title.","title":"Title"},"creator":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words in the creator (author, artist) name.","title":"Creator"},"subject":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words in a subject heading.","title":"Subject"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Item type, lowercase (case-sensitive), for example 'image', 'text', 'sound' or 'moving image'.","title":"Type"},"data_provider":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the contributing institution (dataProvider), for example 'Library of Congress'.","title":"Data Provider"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (at most 100).","title":"Page"}},"title":"search_itemsArguments","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_items_by_date":{"post":{"operationId":"search_items_by_date","summary":"Search DPLA items made within a year or date range (inclusive), optionally with text; same fields as search_items. Use f","description":"Search DPLA items made within a year or date range (inclusive), optionally with text; same fields as search_items. Use for \"What does DPLA have from 1860 to 1865 about the Civil War\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_after":{"description":"Earliest date, a year or full date such as '1860' or '1860-04-12'.","maxLength":10,"title":"Date After","type":"string"},"date_before":{"description":"Latest date, a year or full date such as '1865'.","maxLength":10,"title":"Date Before","type":"string"},"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Words to search in all text fields.","title":"Q"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Item type, lowercase (case-sensitive), for example 'image', 'text', 'sound' or 'moving image'.","title":"Type"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (at most 100).","title":"Page"}},"required":["date_after","date_before"],"title":"search_items_by_dateArguments","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_items_in_state":{"post":{"operationId":"search_items_in_state","summary":"Search DPLA items about a US state (place metadata), optionally with text; same fields as search_items. Use for \"Find DP","description":"Search DPLA items about a US state (place metadata), optionally with text; same fields as search_items. Use for \"Find DPLA items about Hawaii sugar plantations\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Full state name, for example 'Hawaii'.","maxLength":60,"title":"State","type":"string"},"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Words to search in all text fields.","title":"Q"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Item type, lowercase (case-sensitive), for example 'image', 'text', 'sound' or 'moving image'.","title":"Type"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 100).","title":"Page Size"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (at most 100).","title":"Page"}},"required":["state"],"title":"search_items_in_stateArguments","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_item":{"post":{"operationId":"get_item","summary":"Get one DPLA item by its DPLA id (the id of a search result): title, creator, description, subjects, dates, provider and","description":"Get one DPLA item by its DPLA id (the id of a search result): title, creator, description, subjects, dates, provider and links. Use for \"Show the DPLA item with id 4f2d33c1d6d1c3a1b0d5f8a8e63b9c1e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_id":{"description":"DPLA item id (32 hex characters), for example '4f2d33c1d6d1c3a1b0d5f8a8e63b9c1e'.","maxLength":40,"title":"Item Id","type":"string"}},"required":["item_id"],"title":"get_itemArguments","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/facet_counts":{"post":{"operationId":"facet_counts","summary":"Count DPLA items for a text query grouped by one field (type, subject, provider, institution, language, state or format)","description":"Count DPLA items for a text query grouped by one field (type, subject, provider, institution, language, state or format); returns the most common values. Use for \"Which institutions contribute DPLA items about jazz\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Words to search in all text fields, for example 'jazz'.","maxLength":300,"title":"Q","type":"string"},"facets":{"description":"Field to group by.","enum":["sourceResource.type","sourceResource.subject.name","provider.name","dataProvider","sourceResource.language.name","sourceResource.spatial.state","sourceResource.format"],"title":"Facets","type":"string"},"page_size":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Items to return alongside the facets (1 to 10).","title":"Page Size"}},"required":["q","facets"],"title":"facet_countsArguments","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_collections":{"post":{"operationId":"search_collections","summary":"Search DPLA collections (groups of related items) by text; returns the collection records as the API sends them. Use for","description":"Search DPLA collections (groups of related items) by text; returns the collection records as the API sends them. Use for \"Find DPLA collections about Route 66\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Words to search in collection records.","maxLength":200,"title":"Q","type":"string"},"page_size":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many collections per page (1 to 25).","title":"Page Size"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (at most 100).","title":"Page"}},"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}}}}