{"openapi":"3.1.0","info":{"title":"Europeana (BYOK) API","version":"0.1.0","description":"Europeana (BYOK) lets an AI assistant read your own Europeana data through the Europeana API with a key you supply (Europeana API key). Read-only: 6 tools (search_items, search_reusable_media, search_by_theme, search_by_colour, facet_counts, get_record). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-europeana.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-europeana/docs"},"termsOfService":"https://connectorbay.com/byok-europeana/terms"},"servers":[{"url":"https://byok-europeana.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-europeana/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 Europeana records by text with optional filters (type, country, year via qf), reusability and media presence; ret","description":"Search Europeana records by text with optional filters (type, country, year via qf), reusability and media presence; returns title, creator, year, type, provider, rights and links. Use for \"Search Europeana for photographs of Amsterdam canals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms; supports field queries such as 'who:rembrandt' and phrases in quotes, for example 'amsterdam canal'.","maxLength":300,"title":"Query","type":"string"},"qf":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra filter on a field, for example 'TYPE:IMAGE', 'COUNTRY:france' or 'YEAR:1900'.","title":"Qf"},"reusability":{"anyOf":[{"enum":["open","restricted","permission"],"type":"string"},{"type":"null"}],"default":null,"description":"Copyright filter: open, restricted or permission.","title":"Reusability"},"media":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only records with a resolvable link to the full media file.","title":"Media"},"thumbnail":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only records that have a thumbnail.","title":"Thumbnail"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field and direction, for example 'timestamp_update+desc'; default is relevance.","title":"Sort"},"profile":{"anyOf":[{"enum":["minimal","standard"],"type":"string"},{"type":"null"}],"default":"standard","description":"Detail level: minimal or standard (more metadata per record).","title":"Profile"},"rows":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":12,"description":"How many records to return (1 to 100).","title":"Rows"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first record, starting at 1; start plus rows must stay within the first 1000 results.","title":"Start"}},"required":["query"],"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_reusable_media":{"post":{"operationId":"search_reusable_media","summary":"Search Europeana for records that carry an open (freely reusable) rights statement and have a resolvable full media file","description":"Search Europeana for records that carry an open (freely reusable) rights statement and have a resolvable full media file; same fields as search_items. Use for \"Find openly licensed images of windmills on Europeana\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'windmill'.","maxLength":300,"title":"Query","type":"string"},"qf":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra filter on a field, for example 'TYPE:IMAGE', 'COUNTRY:france' or 'YEAR:1900'.","title":"Qf"},"reusability":{"anyOf":[{"enum":["open","restricted","permission"],"type":"string"},{"type":"null"}],"default":"open","description":"Copyright filter: open, restricted or permission.","title":"Reusability"},"media":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to keep only records with a resolvable link to the full media file.","title":"Media"},"profile":{"anyOf":[{"enum":["minimal","standard"],"type":"string"},{"type":"null"}],"default":"standard","description":"Detail level: minimal or standard (more metadata per record).","title":"Profile"},"rows":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":12,"description":"How many records to return (1 to 100).","title":"Rows"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first record, starting at 1; start plus rows must stay within the first 1000 results.","title":"Start"}},"required":["query"],"title":"search_reusable_mediaArguments","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_theme":{"post":{"operationId":"search_by_theme","summary":"Search within one of Europeana's thematic collections (art, music, newspaper, photography, and others); same fields as s","description":"Search within one of Europeana's thematic collections (art, music, newspaper, photography, and others); same fields as search_items. Use for \"Show newspaper records on Europeana mentioning the 1969 moon landing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'moon landing'.","maxLength":300,"title":"Query","type":"string"},"theme":{"description":"Thematic collection to search in.","enum":["archaeology","art","fashion","industrial","manuscript","map","migration","music","nature","newspaper","photography","sport","ww1"],"title":"Theme","type":"string"},"qf":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra filter on a field, for example 'TYPE:IMAGE', 'COUNTRY:france' or 'YEAR:1900'.","title":"Qf"},"profile":{"anyOf":[{"enum":["minimal","standard"],"type":"string"},{"type":"null"}],"default":"standard","description":"Detail level: minimal or standard (more metadata per record).","title":"Profile"},"rows":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":12,"description":"How many records to return (1 to 100).","title":"Rows"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first record, starting at 1; start plus rows must stay within the first 1000 results.","title":"Start"}},"required":["query","theme"],"title":"search_by_themeArguments","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_colour":{"post":{"operationId":"search_by_colour","summary":"Search Europeana images whose colours include a given colour (hex code) for a text query; same fields as search_items. U","description":"Search Europeana images whose colours include a given colour (hex code) for a text query; same fields as search_items. Use for \"Find blue paintings of the sea on Europeana\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'sea'.","maxLength":300,"title":"Query","type":"string"},"colourpalette":{"description":"Hex colour code to match, for example '#0000FF'.","maxLength":9,"title":"Colourpalette","type":"string"},"qf":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra filter on a field, for example 'TYPE:IMAGE', 'COUNTRY:france' or 'YEAR:1900'.","title":"Qf"},"profile":{"anyOf":[{"enum":["minimal","standard"],"type":"string"},{"type":"null"}],"default":"standard","description":"Detail level: minimal or standard (more metadata per record).","title":"Profile"},"rows":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":12,"description":"How many records to return (1 to 100).","title":"Rows"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first record, starting at 1; start plus rows must stay within the first 1000 results.","title":"Start"}},"required":["query","colourpalette"],"title":"search_by_colourArguments","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 Europeana records for a query grouped by one field such as TYPE, COUNTRY, LANGUAGE, PROVIDER, RIGHTS or YEAR; retu","description":"Count Europeana records for a query grouped by one field such as TYPE, COUNTRY, LANGUAGE, PROVIDER, RIGHTS or YEAR; returns each value with its count and no records. Use for \"How many Europeana records about Vermeer are there per country\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search terms, for example 'vermeer'.","maxLength":300,"title":"Query","type":"string"},"facet":{"description":"Field to group by, for example COUNTRY.","enum":["TYPE","COUNTRY","LANGUAGE","PROVIDER","DATA_PROVIDER","RIGHTS","YEAR","REUSABILITY","MIME_TYPE"],"title":"Facet","type":"string"},"qf":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Extra filter on a field, for example 'TYPE:IMAGE', 'COUNTRY:france' or 'YEAR:1900'.","title":"Qf"},"profile":{"anyOf":[{"const":"facets","type":"string"},{"type":"null"}],"default":"facets","description":"Use 'facets' (the only valid value for this tool).","title":"Profile"},"rows":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Records to return alongside the counts (0 for counts only).","title":"Rows"}},"required":["query","facet"],"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/get_record":{"post":{"operationId":"get_record","summary":"Get the full Europeana record by dataset id and local id (the two parts of a record id like /90402/RP_P_1984_87): title,","description":"Get the full Europeana record by dataset id and local id (the two parts of a record id like /90402/RP_P_1984_87): title, type, year, language, country, provider, proxies and aggregations with media links. Use for \"Show the full Europeana record 90402/RP_P_1984_87\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Dataset id, the first part of a Europeana record id, for example '90402'.","maxLength":40,"title":"Dataset Id","type":"string"},"local_id":{"description":"Local id, the second part of a Europeana record id, for example 'RP_P_1984_87'.","maxLength":200,"title":"Local Id","type":"string"}},"required":["dataset_id","local_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}}}}