{"openapi":"3.1.0","info":{"title":"Etsy (BYOK) API","version":"0.1.0","description":"Etsy (BYOK) lets an AI assistant read your own Etsy data through the Etsy API with a key you supply (keystring:shared_secret (paste both joined by a colon)). Read-only: 10 tools (search_active_listings, get_listing, find_shops, get_shop, list_shop_active_listings, list_shop_sections, list_shop_reviews, list_listing_reviews, get_buyer_taxonomy, list_shipping_carriers). 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-etsy.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-etsy/docs"},"termsOfService":"https://connectorbay.com/byok-etsy/terms"},"servers":[{"url":"https://byok-etsy.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-etsy/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_active_listings":{"post":{"operationId":"search_active_listings","summary":"Search active Etsy listings by keywords with optional price range, category (taxonomy id), seller location and sort orde","description":"Search active Etsy listings by keywords with optional price range, category (taxonomy id), seller location and sort order. Use for \"Find handmade ceramic mugs on Etsy under 30 dollars\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keywords":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words that must appear in the listings, for example 'ceramic mug'.","title":"Keywords"},"sort_on":{"anyOf":[{"enum":["created","price","updated","score"],"type":"string"},{"type":"null"}],"default":"created","description":"Sort by created, price, updated or score (sorting by price or score needs keywords).","title":"Sort On"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Direction: asc or desc.","title":"Sort Order"},"min_price":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Lowest price in the shop currency.","title":"Min Price"},"max_price":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Highest price in the shop currency.","title":"Max Price"},"taxonomy_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only listings in this buyer taxonomy node id (see get_buyer_taxonomy).","title":"Taxonomy Id"},"shop_location":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only shops in this location, for example 'Portugal'.","title":"Shop Location"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip before the first one, for paging.","title":"Offset"}},"title":"search_active_listingsArguments","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_listing":{"post":{"operationId":"get_listing","summary":"Get one Etsy listing by id: title, price, quantity, state, tags, favourites, views and url. Use for \"Show me Etsy listin","description":"Get one Etsy listing by id: title, price, quantity, state, tags, favourites, views and url. Use for \"Show me Etsy listing 987654321\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"listing_id":{"description":"Numeric Etsy listing id.","title":"Listing Id","type":"integer"}},"required":["listing_id"],"title":"get_listingArguments","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_shops":{"post":{"operationId":"find_shops","summary":"Find Etsy shops by name; returns shop ids, titles, countries, active listing counts and review averages. Use for \"Find t","description":"Find Etsy shops by name; returns shop ids, titles, countries, active listing counts and review averages. Use for \"Find the Etsy shop called ClayAndCo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_name":{"description":"Shop name to search for.","maxLength":100,"title":"Shop Name","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip before the first one, for paging.","title":"Offset"}},"required":["shop_name"],"title":"find_shopsArguments","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_shop":{"post":{"operationId":"get_shop","summary":"Get one Etsy shop by id: title, announcement, currency, active listing count, sales count, reviews and location. Use for","description":"Get one Etsy shop by id: title, announcement, currency, active listing count, sales count, reviews and location. Use for \"How many sales and reviews does Etsy shop 12345678 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_id":{"description":"Numeric Etsy shop id (find it with find_shops).","title":"Shop Id","type":"integer"}},"required":["shop_id"],"title":"get_shopArguments","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_shop_active_listings":{"post":{"operationId":"list_shop_active_listings","summary":"List the active listings of one shop, optionally filtered by keywords and sorted. Use for \"What is Etsy shop 12345678 se","description":"List the active listings of one shop, optionally filtered by keywords and sorted. Use for \"What is Etsy shop 12345678 selling right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_id":{"description":"Numeric Etsy shop id (find it with find_shops).","title":"Shop Id","type":"integer"},"keywords":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words that must appear in the listing.","title":"Keywords"},"sort_on":{"anyOf":[{"enum":["created","price","updated","score"],"type":"string"},{"type":"null"}],"default":"created","description":"Sort by created, price, updated or score.","title":"Sort On"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Direction: asc or desc.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip before the first one, for paging.","title":"Offset"}},"required":["shop_id"],"title":"list_shop_active_listingsArguments","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_shop_sections":{"post":{"operationId":"list_shop_sections","summary":"List the sections a shop groups its listings into, with the number of active listings in each. Use for \"What sections do","description":"List the sections a shop groups its listings into, with the number of active listings in each. Use for \"What sections does Etsy shop 12345678 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_id":{"description":"Numeric Etsy shop id (find it with find_shops).","title":"Shop Id","type":"integer"}},"required":["shop_id"],"title":"list_shop_sectionsArguments","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_shop_reviews":{"post":{"operationId":"list_shop_reviews","summary":"List buyer reviews of a shop with rating, review text, language and date. Use for \"What do buyers say about Etsy shop 12","description":"List buyer reviews of a shop with rating, review text, language and date. Use for \"What do buyers say about Etsy shop 12345678\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_id":{"description":"Numeric Etsy shop id (find it with find_shops).","title":"Shop Id","type":"integer"},"min_created":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only reviews created at or after this Unix timestamp.","title":"Min Created"},"max_created":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only reviews created at or before this Unix timestamp.","title":"Max Created"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip before the first one, for paging.","title":"Offset"}},"required":["shop_id"],"title":"list_shop_reviewsArguments","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_listing_reviews":{"post":{"operationId":"list_listing_reviews","summary":"List buyer reviews of one listing with rating, review text, language and date. Use for \"Are the reviews for Etsy listing","description":"List buyer reviews of one listing with rating, review text, language and date. Use for \"Are the reviews for Etsy listing 987654321 good\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"listing_id":{"description":"Numeric Etsy listing id.","title":"Listing Id","type":"integer"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip before the first one, for paging.","title":"Offset"}},"required":["listing_id"],"title":"list_listing_reviewsArguments","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_buyer_taxonomy":{"post":{"operationId":"get_buyer_taxonomy","summary":"List Etsy's buyer-facing category tree (top level nodes with id, name, level and parent) to find taxonomy ids for search","description":"List Etsy's buyer-facing category tree (top level nodes with id, name, level and parent) to find taxonomy ids for searches. Use for \"What are Etsy's top-level categories\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_buyer_taxonomyArguments","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_shipping_carriers":{"post":{"operationId":"list_shipping_carriers","summary":"List the shipping carriers Etsy supports for an origin country, with their domestic and international mail classes. Use ","description":"List the shipping carriers Etsy supports for an origin country, with their domestic and international mail classes. Use for \"Which carriers does Etsy support when shipping from Germany\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin_country_iso":{"description":"ISO 3166-1 alpha-2 code of the shipping origin country, for example 'DE'.","maxLength":2,"title":"Origin Country Iso","type":"string"}},"required":["origin_country_iso"],"title":"list_shipping_carriersArguments","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}}}}