{"openapi":"3.1.0","info":{"title":"Rakuten Web Service (BYOK) API","version":"0.1.0","description":"Rakuten Web Service (BYOK) lets an AI assistant read your own Rakuten Web Service data through the Rakuten Web Service API with a key you supply (application ID). Read-only: 6 tools (search_items, list_shop_items, get_item_by_code, search_genres, search_attributes, get_item_ranking). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-rakuten.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-rakuten/docs"},"termsOfService":"https://connectorbay.com/byok-rakuten/terms"},"servers":[{"url":"https://byok-rakuten.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-rakuten/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 items listed on Rakuten Ichiba by keyword, optionally limited by genre, price range and availability. Returns nam","description":"Search items listed on Rakuten Ichiba by keyword, optionally limited by genre, price range and availability. Returns name, code, price, URL, shop and review summary. Japanese keywords work best. Use for \"Find rice cookers on Rakuten Ichiba under 20000 yen, cheapest first\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keyword":{"description":"Search words separated by spaces (all must match), up to 128 single-byte characters, each at least 2 characters.","maxLength":128,"title":"Keyword","type":"string"},"genre_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Rakuten Ichiba genre ID to limit the search (look it up with search_genres).","title":"Genre Id"},"min_price":{"anyOf":[{"maximum":999999998,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Lowest item price in yen.","title":"Min Price"},"max_price":{"anyOf":[{"maximum":999999998,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Highest item price in yen.","title":"Max Price"},"availability":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":1,"description":"0 for all items, 1 for items in stock only.","title":"Availability"},"sort":{"anyOf":[{"enum":["standard","+itemPrice","-itemPrice","+reviewCount","-reviewCount","+reviewAverage","-reviewAverage","+updateTimestamp","-updateTimestamp"],"type":"string"},{"type":"null"}],"default":"standard","description":"Order of results: standard, +itemPrice or -itemPrice (price), +reviewCount or -reviewCount, +reviewAverage or -reviewAverage, +updateTimestamp or -updateTimestamp.","title":"Sort"},"hits":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many items to return per page (1 to 30).","title":"Hits"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Result page, 1 to 100.","title":"Page"}},"required":["keyword"],"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/list_shop_items":{"post":{"operationId":"list_shop_items","summary":"List items of one Rakuten Ichiba shop by its shop code (the part of the shop URL after rakuten.co.jp/), optionally with ","description":"List items of one Rakuten Ichiba shop by its shop code (the part of the shop URL after rakuten.co.jp/), optionally with a keyword. Use for \"What items does the Rakuten shop 'example-shop' sell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_code":{"description":"Shop code, the 'xyz' in https://www.rakuten.co.jp/xyz/.","maxLength":200,"title":"Shop Code","type":"string"},"keyword":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Optional words to narrow the shop's items.","title":"Keyword"},"availability":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":1,"description":"0 for all items, 1 for items in stock only.","title":"Availability"},"sort":{"anyOf":[{"enum":["standard","+itemPrice","-itemPrice","+reviewCount","-reviewCount","+reviewAverage","-reviewAverage","+updateTimestamp","-updateTimestamp"],"type":"string"},{"type":"null"}],"default":"standard","description":"Order of results: standard, +itemPrice or -itemPrice (price), +reviewCount or -reviewCount, +reviewAverage or -reviewAverage, +updateTimestamp or -updateTimestamp.","title":"Sort"},"hits":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many items to return per page (1 to 30).","title":"Hits"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Result page, 1 to 100.","title":"Page"}},"required":["shop_code"],"title":"list_shop_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/get_item_by_code":{"post":{"operationId":"get_item_by_code","summary":"Look up one Rakuten Ichiba item by its item code (form 'shopcode:itemnumber'), returning price, availability, shop and r","description":"Look up one Rakuten Ichiba item by its item code (form 'shopcode:itemnumber'), returning price, availability, shop and review summary. Use for \"Show Rakuten item example-shop:10000001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_code":{"description":"Item code in the form shop:1234, as returned by search_items.","maxLength":200,"title":"Item Code","type":"string"}},"required":["item_code"],"title":"get_item_by_codeArguments","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_genres":{"post":{"operationId":"search_genres","summary":"Show a Rakuten Ichiba genre with its parent, sibling and child genres. Use genre ID 0 to list the top-level genres. Use ","description":"Show a Rakuten Ichiba genre with its parent, sibling and child genres. Use genre ID 0 to list the top-level genres. Use for \"What are the top-level genres on Rakuten Ichiba\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre_id":{"description":"Genre ID to look up; 0 returns the root with its first-level children.","maxLength":200,"title":"Genre Id","type":"string"}},"required":["genre_id"],"title":"search_genresArguments","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_attributes":{"post":{"operationId":"search_attributes","summary":"List the product attributes defined for a Rakuten Ichiba genre, or one attribute when its ID is given. Use for \"Which at","description":"List the product attributes defined for a Rakuten Ichiba genre, or one attribute when its ID is given. Use for \"Which attributes can items in genre 100283 have on Rakuten\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre_id":{"description":"Genre ID whose attributes to list.","maxLength":200,"title":"Genre Id","type":"string"},"attribute_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional attribute ID to fetch only that attribute.","title":"Attribute Id"}},"required":["genre_id"],"title":"search_attributesArguments","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_ranking":{"post":{"operationId":"get_item_ranking","summary":"Get the Rakuten Ichiba sales ranking, overall or for one genre, or for an age group and gender (genre cannot be combined","description":"Get the Rakuten Ichiba sales ranking, overall or for one genre, or for an age group and gender (genre cannot be combined with age or gender). Use for \"What are the best-selling items on Rakuten Ichiba right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Genre ID for a genre ranking; leave empty for the overall ranking. Do not combine with age or sex.","title":"Genre Id"},"age":{"anyOf":[{"enum":[10,20,30,40,50],"type":"integer"},{"type":"null"}],"default":null,"description":"Age group: 10, 20, 30, 40 or 50 (50 and over).","title":"Age"},"sex":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"0 for male, 1 for female; can be combined with age.","title":"Sex"},"period":{"anyOf":[{"const":"realtime","type":"string"},{"type":"null"}],"default":null,"description":"Set to realtime for real-time ranking data.","title":"Period"},"page":{"anyOf":[{"maximum":34,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Result page, 1 to 34 (30 ranks per page).","title":"Page"}},"title":"get_item_rankingArguments","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}}}}