{"openapi":"3.1.0","info":{"title":"The Bidit Registry API","version":"1.0.0","summary":"Does this retailer take offers, and does it price match?","description":"A public index of retailers and their flexibility on price. Two headline answers per retailer: whether a shopper can make it an offer instead of paying the listed price (yes or not yet, read from Bidit's engine), and whether it price matches (yes, no or unknown, verified by a person against the retailer's own published policy). Nothing is stated that has not been verified. Also served as an MCP server at /api/mcp with the same four tools.","license":{"name":"CC BY 4.0","identifier":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/"},"contact":{"name":"Bidit","url":"https://bidit.com.au"},"x-attribution":"The Bidit Registry (registry.bidit.com.au)"},"servers":[{"url":"https://registry.bidit.com.au"}],"tags":[{"name":"tools","description":"The four questions an agent asks, one call each"},{"name":"registry","description":"Whole-market and single-retailer records"},{"name":"intents","description":"Registering what a shopper would pay at a retailer that does not take offers yet"}],"paths":{"/api/tools/will_price_match":{"get":{"tags":["tools"],"operationId":"will_price_match","summary":"Will this retailer match a competitor's lower price?","description":"Returns whether a retailer publishes a policy of matching a competitor's lower price, with the verified terms, exclusions, how to claim, a sentence quoted from the policy and the policy page. answer is yes (a person has verified the published policy), no (a person looked and found none) or unknown (not verified). Whether a particular competitor price qualifies depends on the terms returned.","parameters":[{"name":"retailer","in":"query","required":true,"description":"Retailer name, domain or Registry slug, e.g. 'JB Hi-Fi', 'jbhifi.com.au' or 'jbhifi'","schema":{"type":"string"}},{"name":"competitor_price","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0},"description":"The lower price the shopper found, in the retailer's currency. Echoed back."},{"name":"product","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The answer with the verified terms","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","const":"will_price_match"},"retailer":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string","format":"uri"},"country":{"type":"string","description":"ISO 3166 two-letter code"},"currency":{"type":"string"},"category":{"type":["string","null"]},"category_label":{"type":"string"},"page":{"type":"string","format":"uri","description":"The retailer's page on the Registry"}}},"product":{"type":["string","null"]},"competitor_price":{"type":["number","null"]},"answer":{"type":"string","enum":["yes","no","unknown"],"description":"yes: a person verified the retailer's published price-match policy. no: a person looked and found none. unknown: not verified; say nothing either way."},"terms":{"type":["string","null"],"description":"The conditions, in plain sentences"},"exclusions":{"type":["string","null"]},"how_to_claim":{"type":["string","null"]},"policy_url":{"type":["string","null"],"format":"uri","description":"The retailer's own policy page"},"evidence_quote":{"type":["string","null"],"description":"One sentence copied from the policy page"},"verified_at":{"type":["string","null"],"format":"date-time"},"verified_how":{"type":["string","null"]},"message":{"type":"string","description":"A sentence an agent can say to the shopper"},"takes_offers":{"type":"boolean"},"can_make_offer":{"type":"string","format":"uri"}},"required":["answer","retailer","message"]}}}},"300":{"description":"The name matched several retailers; pick one from candidates and call again with its slug","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}},"404":{"description":"Not in the Registry. Assume nothing about the retailer's policies","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}}}}},"/api/tools/price_policy":{"get":{"tags":["tools"],"operationId":"price_policy","summary":"Everything verified about how a retailer handles price","description":"Returns everything the Registry has verified about how a retailer handles price: whether it takes offers through Bidit, whether it price matches and on what terms, how it runs promotions, and its clearance page. Fields are null where nothing has been verified.","parameters":[{"name":"retailer","in":"query","required":true,"description":"Retailer name, domain or Registry slug, e.g. 'JB Hi-Fi', 'jbhifi.com.au' or 'jbhifi'","schema":{"type":"string"}}],"responses":{"200":{"description":"The retailer's verified price policy","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","const":"price_policy"},"retailer":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string","format":"uri"},"country":{"type":"string","description":"ISO 3166 two-letter code"},"currency":{"type":"string"},"category":{"type":["string","null"]},"category_label":{"type":"string"},"page":{"type":"string","format":"uri","description":"The retailer's page on the Registry"}}},"takes_offers":{"type":"boolean"},"offers":{"type":["object","null"],"properties":{"offers_url":{"type":["string","null"]},"max_attempts_per_variant":{"type":["integer","null"]},"how":{"type":"string"}}},"price_match":{"type":"object","properties":{"answer":{"type":"string","enum":["yes","no","unknown"],"description":"yes: a person verified the retailer's published price-match policy. no: a person looked and found none. unknown: not verified; say nothing either way."},"terms":{"type":["string","null"],"description":"The conditions, in plain sentences"},"exclusions":{"type":["string","null"]},"how_to_claim":{"type":["string","null"]},"policy_url":{"type":["string","null"],"format":"uri","description":"The retailer's own policy page"},"evidence_quote":{"type":["string","null"],"description":"One sentence copied from the policy page"},"verified_at":{"type":["string","null"],"format":"date-time"},"verified_how":{"type":["string","null"]}}},"promotions":{"type":"object","properties":{"regular_promotions":{"type":["boolean","null"]},"notes":{"type":["string","null"]}}},"clearance_page":{"type":["string","null"],"format":"uri"},"register_interest_url":{"type":["string","null"],"format":"uri"},"page":{"type":"string","format":"uri"}}}}}},"300":{"description":"The name matched several retailers; pick one from candidates and call again with its slug","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}},"404":{"description":"Not in the Registry. Assume nothing about the retailer's policies","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}}}}},"/api/tools/retailers_that_price_match":{"get":{"tags":["tools"],"operationId":"retailers_that_price_match","summary":"Retailers with a verified price-match policy","description":"Returns the retailers whose price-match policy a person has verified, optionally filtered by category and country, each with its terms and policy page. A retailer absent from the list is unverified, not a no.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"electronics, furniture, outdoor, hardware, sports, jewellery, beauty, department, automotive, homewares, office, baby, pets, toys, health, fashion, music"},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166 two-letter code, e.g. AU"}],"responses":{"200":{"description":"The list, verified retailers only","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","const":"retailers_that_price_match"},"country":{"type":["string","null"]},"category":{"type":["string","null"]},"count":{"type":"integer"},"note":{"type":"string"},"retailers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string","format":"uri"},"country":{"type":"string","description":"ISO 3166 two-letter code"},"currency":{"type":"string"},"category":{"type":["string","null"]},"category_label":{"type":"string"},"page":{"type":"string","format":"uri","description":"The retailer's page on the Registry"},"takes_offers":{"type":"boolean"},"terms":{"type":["string","null"]},"how_to_claim":{"type":["string","null"]},"policy_url":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"}}}}}}}}}}}},"/api/tools/can_make_offer":{"get":{"tags":["tools"],"operationId":"can_make_offer","summary":"Can a shopper make this retailer an offer?","description":"Returns whether a shopper can make this retailer an offer instead of paying the listed price. answer is yes (the retailer accepts offers through Bidit now; offers_url is where) or not_yet (the retailer does not; register_interest_url and consent_text describe how a shopper can register the price they would pay). There is no third state.","parameters":[{"name":"retailer","in":"query","required":true,"description":"Retailer name, domain or Registry slug, e.g. 'JB Hi-Fi', 'jbhifi.com.au' or 'jbhifi'","schema":{"type":"string"}}],"responses":{"200":{"description":"yes or not_yet, never anything in between","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","const":"can_make_offer"},"retailer":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string","format":"uri"},"country":{"type":"string","description":"ISO 3166 two-letter code"},"currency":{"type":"string"},"category":{"type":["string","null"]},"category_label":{"type":"string"},"page":{"type":"string","format":"uri","description":"The retailer's page on the Registry"}}},"answer":{"type":"string","enum":["yes","not_yet"]},"negotiable":{"type":"boolean"},"message":{"type":"string"},"offers_url":{"type":["string","null"]},"max_attempts_per_variant":{"type":["integer","null"]},"register_interest_url":{"type":["string","null"],"format":"uri"},"consent_text":{"type":["string","null"],"description":"Show to the shopper word for word before registering their intended price"},"price_match":{"type":"string","enum":["yes","no","unknown"]},"answer_url":{"type":"string","format":"uri"}},"required":["answer","negotiable","retailer","message"]}}}},"300":{"description":"The name matched several retailers; pick one from candidates and call again with its slug","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}},"404":{"description":"Not in the Registry. Assume nothing about the retailer's policies","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["ambiguous_retailer","unknown_retailer"]},"message":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string"}}}}}}}}}}}},"/api/registry":{"get":{"tags":["registry"],"operationId":"registry","summary":"Every retailer in the Registry, with verified facts","description":"The whole-market feed. Also at /.well-known/negotiability.json. negotiable=true means the retailer is in the engine's live list and an offer can be made now. facts.price_match is true or false only after verification; null means unknown.","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"ISO 3166 two-letter code"}],"responses":{"200":{"description":"The feed","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"merchants":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/merchants/{slug}":{"get":{"tags":["registry"],"operationId":"merchant","summary":"One retailer's record, with the register-interest recipe when it does not take offers","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown retailer"}}}},"/api/intents":{"post":{"tags":["intents"],"operationId":"register_intent","summary":"Register the price a shopper would pay at a retailer that does not take offers yet","description":"Requires the shopper's explicit consent to the consent_text returned by can_make_offer. Refused (409) for retailers that already take offers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant_slug","product","intended_price","email","consent"],"properties":{"merchant_slug":{"type":"string"},"product":{"type":"string","minLength":2,"maxLength":300},"intended_price":{"type":"number","exclusiveMinimum":0},"ticket_price":{"type":["number","null"],"exclusiveMinimum":0},"email":{"type":"string","format":"email"},"consent":{"type":"boolean","const":true},"source":{"type":"string","enum":["web","assistant"]}}}}}},"responses":{"200":{"description":"Registered"},"400":{"description":"Validation failed"},"404":{"description":"Unknown retailer"},"409":{"description":"The retailer already takes offers; make the offer instead"}}}},"/api/dataset":{"get":{"tags":["registry"],"operationId":"dataset","summary":"The Registry as a flat file for research and reuse (CC BY 4.0)","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","json"],"default":"csv"}}],"responses":{"200":{"description":"One row per retailer; price-match fields filled only where verified","content":{"text/csv":{},"application/json":{}}}}}},"/api/mcp":{"post":{"tags":["tools"],"operationId":"mcp","summary":"The same four tools over MCP (Streamable HTTP, JSON-RPC 2.0, stateless)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{},"method":{"type":"string","enum":["initialize","ping","tools/list","tools/call"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"}}}}}}