{"openapi":"3.1.0","info":{"title":"UPCitemdb (BYOK) API","version":"0.1.0","description":"UPCitemdb (BYOK) lets an AI assistant read your own UPCitemdb data through the UPCitemdb API with a key you supply (UPCitemdb user key (DEV or PRO plan)). Read-only: 8 tools (lookup_barcode, get_barcode_offers, get_recorded_price_range, search_products, search_by_brand, search_by_category, find_by_model_number, search_books). 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-upcitemdb.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-upcitemdb/docs"},"termsOfService":"https://connectorbay.com/byok-upcitemdb/terms"},"servers":[{"url":"https://byok-upcitemdb.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-upcitemdb/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/lookup_barcode":{"post":{"operationId":"lookup_barcode","summary":"Look up a product by UPC-A, EAN-13 or GTIN barcode: title, brand, model, category, size, weight, price range and images.","description":"Look up a product by UPC-A, EAN-13 or GTIN barcode: title, brand, model, category, size, weight, price range and images. Up to 10 comma-separated codes. Counts against the plan's daily lookup allowance. Use for \"What product has barcode 0885909950805\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"upc":{"description":"Barcode (UPC-A, EAN-13 or GTIN-14), digits only; up to 10 separated by commas.","maxLength":200,"title":"Upc","type":"string"}},"required":["upc"],"title":"lookup_barcodeArguments","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_barcode_offers":{"post":{"operationId":"get_barcode_offers","summary":"List the online merchants currently offering a barcode's product, with price, condition, shipping and availability. Use ","description":"List the online merchants currently offering a barcode's product, with price, condition, shipping and availability. Use for \"Who sells barcode 0885909950805 and for how much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"upc":{"description":"Barcode (UPC-A, EAN-13 or GTIN-14), digits only.","maxLength":20,"title":"Upc","type":"string"}},"required":["upc"],"title":"get_barcode_offersArguments","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_recorded_price_range":{"post":{"operationId":"get_recorded_price_range","summary":"Show the lowest and highest price ever recorded for a barcode's product. Use for \"What are the lowest and highest record","description":"Show the lowest and highest price ever recorded for a barcode's product. Use for \"What are the lowest and highest recorded prices for barcode 0885909950805\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"upc":{"description":"Barcode (UPC-A, EAN-13 or GTIN-14), digits only; up to 10 separated by commas.","maxLength":200,"title":"Upc","type":"string"}},"required":["upc"],"title":"get_recorded_price_rangeArguments","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_products":{"post":{"operationId":"search_products","summary":"Search the product database by keywords and get matching products with barcodes, brands and price ranges, 10 per page. C","description":"Search the product database by keywords and get matching products with barcodes, brands and price ranges, 10 per page. Counts against the plan's daily search allowance. Use for \"Find products matching 'iphone 6 64gb'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"s":{"description":"Search keywords.","maxLength":200,"title":"S","type":"string"},"type":{"anyOf":[{"const":"product","type":"string"},{"type":"null"}],"default":"product","description":"Item type, always 'product'.","title":"Type"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging (multiples of 10).","title":"Offset"},"match_mode":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Match mode, always 1 (most relevant products first).","title":"Match Mode"}},"required":["s"],"title":"search_productsArguments","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_brand":{"post":{"operationId":"search_by_brand","summary":"Search products by keywords limited to one brand. Use for \"Find Apple products matching 'watch'\".","description":"Search products by keywords limited to one brand. Use for \"Find Apple products matching 'watch'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"s":{"description":"Search keywords.","maxLength":200,"title":"S","type":"string"},"brand":{"description":"Brand name to restrict to.","maxLength":100,"title":"Brand","type":"string"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging (multiples of 10).","title":"Offset"},"match_mode":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Match mode, always 1 (most relevant products first).","title":"Match Mode"}},"required":["s","brand"],"title":"search_by_brandArguments","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_category":{"post":{"operationId":"search_by_category","summary":"Search products by keywords limited to a category name. Use for \"Find products matching 'charger' in the phones category","description":"Search products by keywords limited to a category name. Use for \"Find products matching 'charger' in the phones category\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"s":{"description":"Search keywords.","maxLength":200,"title":"S","type":"string"},"category":{"description":"Category name or fragment to restrict to.","maxLength":100,"title":"Category","type":"string"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging (multiples of 10).","title":"Offset"},"match_mode":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Match mode, always 1 (most relevant products first).","title":"Match Mode"}},"required":["s","category"],"title":"search_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/find_by_model_number":{"post":{"operationId":"find_by_model_number","summary":"Search products by keywords restricted to a manufacturer model number. Use for \"Find the product with model number MG5A2","description":"Search products by keywords restricted to a manufacturer model number. Use for \"Find the product with model number MG5A2LL\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"s":{"description":"Search keywords.","maxLength":200,"title":"S","type":"string"},"model":{"description":"Model number to restrict to.","maxLength":100,"title":"Model","type":"string"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging (multiples of 10).","title":"Offset"},"match_mode":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Match mode, always 1 (most relevant products first).","title":"Match Mode"}},"required":["s","model"],"title":"find_by_model_numberArguments","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_books":{"post":{"operationId":"search_books","summary":"Search books by title or author keywords and get their barcodes (ISBN-13 as EAN). Use for \"Find books about 'lean manufa","description":"Search books by title or author keywords and get their barcodes (ISBN-13 as EAN). Use for \"Find books about 'lean manufacturing'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"s":{"description":"Search keywords.","maxLength":200,"title":"S","type":"string"},"type":{"anyOf":[{"const":"book","type":"string"},{"type":"null"}],"default":"book","description":"Item type, always 'book'.","title":"Type"},"offset":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result offset for paging (multiples of 10).","title":"Offset"},"match_mode":{"anyOf":[{"const":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Match mode, always 1 (most relevant products first).","title":"Match Mode"}},"required":["s"],"title":"search_booksArguments","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}}}}