{"openapi":"3.1.0","info":{"title":"BuyWise Agent API","version":"1.0.0","summary":"Trust signals about brands and product listings, for shopping agents.","description":"Check brands and product listings for white-label signs, quality, price vs typical, fake discounts, review credibility and seller legitimacy, and brands for what kind of brand each is, its reputation and its price positioning. Every finding carries a tone (good, warn, bad) and a confidence. There is never a buy or avoid verdict: the agent decides for its user. No key needed: 1000 free checks a day. Each brand or listing checked counts as one check. Days are UTC. An API key is optional (see the apiKey scheme). Every successful answer carries quota: plan, used, limit and resetsAt, plus period on Pro. The same checks are available over MCP at https://api.buywise.fyi/mcp. Callers without a key can also pay per check over REST with x402: $0.01 per check in USDC on Base. MCP never asks for payment.","contact":{"name":"BuyWise support","email":"support@buywise.fyi","url":"https://buywise.fyi"}},"servers":[{"url":"https://api.buywise.fyi"}],"externalDocs":{"description":"Guide for agents and the people wiring them up","url":"https://api.buywise.fyi/llms.txt"},"tags":[{"name":"brands","description":"Findings about brands."},{"name":"products","description":"Findings about product listings."}],"security":[{},{"apiKey":[]}],"paths":{"/agent/v1/brand":{"get":{"operationId":"getBrand","summary":"Check a brand","description":"What kind of brand it is (established, independent maker, store brand, generic white-label), its build-quality reputation and its price positioning. Signals with confidence, not a verdict. One check.","tags":["brands"],"parameters":[{"name":"name","in":"query","required":true,"description":"Brand name as the listing shows it, e.g. \"Anker\". Store wrappers such as \"Visit the Anker Store\" are fine. Up to 200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"Anker"},{"name":"detail","in":"query","required":false,"description":"true (or 1) to include each finding's full probability distribution. Default false.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The brand report.","headers":{"PAYMENT-RESPONSE":{"description":"On a paid (x402) request: base64-encoded JSON SettlementResponse, with the transaction hash.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/LimitReached"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-openai-isConsequential":false}},"/agent/v1/brands":{"post":{"operationId":"checkBrands","summary":"Check several brands","description":"The same report as GET /agent/v1/brand for a batch of brands, in input order. Each brand counts as one check.","tags":["brands"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandsRequest"},"example":{"brands":["Anker","Amazon Basics","ZXQVLM"]}}}},"responses":{"200":{"description":"One report per brand, in input order.","headers":{"PAYMENT-RESPONSE":{"description":"On a paid (x402) request: base64-encoded JSON SettlementResponse, with the transaction hash.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/TooManyItems"},"429":{"$ref":"#/components/responses/LimitReached"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-openai-isConsequential":false}},"/agent/v1/product":{"post":{"operationId":"checkProduct","summary":"Check a product listing","description":"Checks one listing for white-label signs, quality, price vs typical, fake discount, review credibility and seller legitimacy, each with a confidence. Only title is required; each extra field unlocks or sharpens a check. One check, brand report included.","tags":["products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductRequest"},"example":{"product":{"title":"Robot Vacuum Cleaner, 4000Pa Suction, Self-Charging, Was $399.99","brand":"ZXQVLM","price":129.99,"listPrice":399.99,"currency":"USD","url":"https://www.example.com/p/robot-vacuum-4000pa","seller":"ZXQVLM Direct","rating":4.7,"reviewCount":1843}}}}},"responses":{"200":{"description":"The product report.","headers":{"PAYMENT-RESPONSE":{"description":"On a paid (x402) request: base64-encoded JSON SettlementResponse, with the transaction hash.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/BlockedSite"},"429":{"$ref":"#/components/responses/LimitReached"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-openai-isConsequential":false}},"/agent/v1/products":{"post":{"operationId":"checkProducts","summary":"Check several product listings","description":"A batch of listings, checked in parallel, results in input order. Each listing counts as one check. One that can't be checked (blocked site, bad URL, no checks left, service busy) gets a per-item error instead of failing the batch.","tags":["products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsRequest"},"example":{"products":[{"id":"a","title":"Anker 737 Power Bank (PowerCore 24K)","brand":"Anker","price":89.99,"url":"https://www.example.com/p/anker-737"},{"id":"b","title":"Power Bank 50000mAh Fast Charging Portable Charger","price":19.99,"listPrice":59.99,"rating":4.8,"reviewCount":212}]}}}},"responses":{"200":{"description":"One report or per-item error per listing, in input order.","headers":{"PAYMENT-RESPONSE":{"description":"On a paid (x402) request: base64-encoded JSON SettlementResponse, with the transaction hash.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"413":{"$ref":"#/components/responses/TooManyItems"},"429":{"$ref":"#/components/responses/LimitReached"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-openai-isConsequential":false}}},"components":{"schemas":{"ProductInput":{"description":"A product as seen on a store listing. Only title is required; each extra field sharpens the read.","type":"object","properties":{"id":{"description":"Your own id for this product (e.g. an ASIN or list index); echoed back.","type":"string","maxLength":100},"title":{"description":"Product title exactly as the listing shows it.","type":"string","minLength":1,"maxLength":1000},"brand":{"description":"Brand or maker, if the listing names one.","type":"string","maxLength":200},"price":{"description":"What the buyer would pay now, as a number.","type":"number","minimum":0,"maximum":10000000},"currency":{"description":"ISO 4217 code for price and listPrice. Default USD.","type":"string","pattern":"^[A-Za-z]{3}$"},"listPrice":{"description":"The seller's \"was\" / \"list\" / \"typical\" price, if shown.","type":"number","minimum":0,"maximum":10000000},"url":{"description":"Listing URL. Only its domain is used.","type":"string","maxLength":2048},"seller":{"description":"Seller or store name, if different from the site.","type":"string","maxLength":300},"category":{"description":"Product category, e.g. \"Headphones\".","type":"string","maxLength":300},"rating":{"description":"Average star rating out of 5.","type":"number","minimum":0,"maximum":5},"reviewCount":{"description":"Number of ratings or reviews.","type":"integer","minimum":0,"maximum":1000000000},"details":{"description":"Key specs or bullet points as plain text. Longer text is trimmed.","type":"string","maxLength":20000}},"required":["title"]},"BrandsRequest":{"type":"object","properties":{"brands":{"description":"Brand names, 1-50.","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"detail":{"description":"Include each finding's full probability distribution. Default false.","type":"boolean"}},"required":["brands"]},"ProductRequest":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/ProductInput"},"detail":{"description":"Include each finding's full probability distribution. Default false.","type":"boolean"},"includeBrand":{"description":"Also report on the brand the listing names (its brand field), with findings on the brand itself. Default true.","type":"boolean"}},"required":["product"]},"ProductsRequest":{"type":"object","properties":{"products":{"description":"Products, 1-20.","minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/ProductInput"}},"detail":{"description":"Include each finding's full probability distribution. Default false.","type":"boolean"},"includeBrand":{"description":"Also report on the brand the listing names (its brand field), with findings on the brand itself. Default true.","type":"boolean"}},"required":["products"]},"Instinct":{"type":"object","properties":{"aspect":{"type":"string"},"label":{"type":"string"},"finding":{"type":"string"},"tone":{"type":"string","enum":["good","warn","bad"]},"confidence":{"type":"number","minimum":0,"maximum":1},"certainty":{"type":"string","enum":["very likely","likely","unsure"]},"why":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"finding":{"type":"string"},"tone":{"type":"string","enum":["good","warn","bad"]},"p":{"type":"number"}},"required":["finding","tone","p"]}}},"required":["aspect","label","finding","tone","confidence","certainty"]},"BrandReport":{"type":"object","properties":{"query":{"type":"string"},"name":{"type":"string"},"instincts":{"type":"array","items":{"$ref":"#/components/schemas/Instinct"}},"positioning":{"type":"object","properties":{"tier":{"type":"string","enum":["budget","value","mid-range","premium","luxury"]},"confidence":{"type":"number"}},"required":["tier","confidence"]},"summary":{"type":"string"},"evaluatedAt":{"type":"string"},"cache":{"type":"string","enum":["hit","miss","none"]},"error":{"type":"string","enum":["upstream","budget_exhausted"]}},"required":["query","name","instincts","summary","cache"]},"ProductReport":{"type":"object","properties":{"id":{"type":"string"},"instincts":{"type":"array","items":{"$ref":"#/components/schemas/Instinct"}},"counts":{"type":"object","properties":{"good":{"type":"number"},"warn":{"type":"number"},"bad":{"type":"number"}},"required":["good","warn","bad"]},"summary":{"type":"string"},"brand":{"$ref":"#/components/schemas/BrandReport"},"evaluatedAt":{"type":"string"},"cache":{"type":"string","enum":["hit","miss","none"]}},"required":["instincts","counts","summary","evaluatedAt","cache"]},"ProductError":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"string","enum":["bad_request","unauthorized","rate_limited","quota_exceeded","allowance_reached","spend_cap_reached","throttled","budget_exhausted","blocked_site","too_many_items","upstream","payment_required"]},"message":{"type":"string"}},"required":["error","message"]},"BrandRefusal":{"type":"object","properties":{"query":{"type":"string"},"error":{"type":"string","enum":["bad_request","unauthorized","rate_limited","quota_exceeded","allowance_reached","spend_cap_reached","throttled","budget_exhausted","blocked_site","too_many_items","upstream","payment_required"]},"message":{"type":"string"}},"required":["query","error","message"]},"Quota":{"description":"What is left of the allowance after this request.","type":"object","properties":{"plan":{"type":"string","enum":["free","pro"]},"used":{"description":"Checks counted today: free checks, or a Pro license's checks today.","type":"number"},"limit":{"description":"Checks a day; null on Pro, whose allowance is the billing period below.","anyOf":[{"type":"number"},{"type":"null"}]},"resetsAt":{"description":"When the daily count resets: 00:00 UTC.","type":"string"},"period":{"description":"Pro only: the billing period, with its included checks.","type":"object","properties":{"start":{"type":"string"},"end":{"description":"When the included checks come back.","type":"string"},"included":{"type":"number"},"used":{"type":"number"},"extra":{"type":"object","properties":{"enabled":{"type":"boolean"},"used":{"type":"number"},"capCents":{"type":"number"}},"required":["enabled","used","capCents"]}},"required":["start","end","included","used","extra"]}},"required":["plan","used","limit","resetsAt"]},"BrandResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"brand":{"$ref":"#/components/schemas/BrandReport"},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["ok","brand"]},"BrandsResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"brands":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/BrandReport"},{"$ref":"#/components/schemas/BrandRefusal"}]}},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["ok","brands"]},"ProductResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"product":{"$ref":"#/components/schemas/ProductReport"},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["ok","product"]},"ProductsResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"products":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/ProductReport"},{"$ref":"#/components/schemas/ProductError"}]}},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["ok","products"]},"ErrorResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","enum":["bad_request","unauthorized","rate_limited","quota_exceeded","allowance_reached","spend_cap_reached","throttled","budget_exhausted","blocked_site","too_many_items","upstream","payment_required"]},"message":{"type":"string"},"retryAfter":{"type":"number"},"quota":{"$ref":"#/components/schemas/Quota"}},"required":["ok","error","message"]}},"responses":{"BadRequest":{"description":"bad_request: Malformed request. The message names the first bad field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"unauthorized: The API key is malformed, unknown or revoked (leave out Authorization to use the free checks), or this connection needs a BuyWise account connected first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BlockedSite":{"description":"blocked_site: The listing's site isn't checked: banking, health, government, email, sign-in and private hosts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyItems":{"description":"too_many_items: The batch is larger than the limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"LimitReached":{"description":"quota_exceeded: Today's free checks are used up. They come back at 00:00 UTC. allowance_reached: The Pro plan's checks for this billing month are used up. They come back when the next billing month starts. throttled: Today's fair-use limit is reached. It resets at 00:00 UTC. rate_limited: Too many requests this minute. Retry after retryAfter seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unavailable":{"description":"budget_exhausted: The service is busy; try again later. A listing check answers 503; a brand check still answers, with its findings empty and \"error\": \"budget_exhausted\". upstream: A check couldn't be completed. Try again in a moment. Retry after retryAfter seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequired":{"description":"Error \"payment_required\": pay for the request with x402 v2, $0.01 per check in USDC on Base. Sent to a caller without an API key once its free checks are used up (or past its rate limit), or when a payment was refused or didn't settle. Sign the offer in PAYMENT-REQUIRED with any x402 client and resend the same request with PAYMENT-SIGNATURE: you're charged only when the check succeeds. Or use an API key, or retry after retryAfter seconds.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded JSON PaymentRequired (x402 v2): scheme \"exact\", network, USDC asset, payTo and the exact amount for this request, in atomic units. Absent when a settlement failed but may still go through: retry with the same payment, never a new one.","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded JSON SettlementResponse, when a payment failed to settle.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the free checks allow this again, when they will.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Optional. Without it: 1000 free checks a day, 300 requests a minute. \"Authorization: Bearer <BuyWise API key>\": a key's checks count against its own plan, at 1,200 requests a minute. A malformed, unknown or revoked key gets 401, never a silent downgrade to the free checks."}}}}