{"openapi":"3.1.0","info":{"title":"Vera Agent API","version":"1.0.0","description":"REST API for AI agents shopping on Vera. Read endpoints are public; every write needs an agent key, a Vera-Agent header and a mandate."},"servers":[{"url":"https://www.agentsgoshopping.com/api/v1"}],"tags":[{"name":"agents"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Agent key: Authorization: Bearer vera_sk_test_<32 chars>. Writes also need Vera-Agent: <name>/<version>."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string"}},"required":["error","message"]}},"parameters":{}},"paths":{"/search":{"get":{"summary":"Search products (public)","description":"Ranked verified products. Always read `excluded` before choosing.","parameters":[{"schema":{"type":"string","maxLength":200,"description":"Free-text query, e.g. 'hepa filter'."},"required":false,"description":"Free-text query, e.g. 'hepa filter'.","name":"q","in":"query"},{"schema":{"type":"string","maxLength":100,"description":"Device slug from find_device (e.g. philips-ac2729). Free text is resolved when unambiguous."},"required":false,"description":"Device slug from find_device (e.g. philips-ac2729). Free text is resolved when unambiguous.","name":"device","in":"query"},{"schema":{"type":"string","maxLength":50,"description":"Category id: hand-soap, air-filters, vacuum-parts, coffee-kitchen, printer-ink, chargers-cables, batteries."},"required":false,"description":"Category id: hand-soap, air-filters, vacuum-parts, coffee-kitchen, printer-ink, chargers-cables, batteries.","name":"category","in":"query"},{"schema":{"type":"string","maxLength":50,"description":"Part type: hand-soap, filter, battery, charger, cable, descaler, toner, ink-cartridge, jug-filter, dust-bag, accessory-kit, cell."},"required":false,"description":"Part type: hand-soap, filter, battery, charger, cable, descaler, toner, ink-cartridge, jug-filter, dust-bag, accessory-kit, cell.","name":"part_type","in":"query"},{"schema":{"type":"number","description":"Maximum unit price in EUR incl. VAT."},"required":false,"description":"Maximum unit price in EUR incl. VAT.","name":"max_price","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Latest acceptable delivery date (yyyy-mm-dd). Offers that miss it are ineligible."},"required":false,"description":"Latest acceptable delivery date (yyyy-mm-dd). Offers that miss it are ineligible.","name":"deliver_by","in":"query"},{"schema":{"type":"boolean","default":true,"description":"Default true: hide products whose measurements contradict the merchant's claims."},"required":false,"description":"Default true: hide products whose measurements contradict the merchant's claims.","name":"verified_only","in":"query"},{"schema":{"type":"string","maxLength":50},"required":false,"name":"merchant","in":"query"},{"schema":{"type":"string","maxLength":12,"description":"Delivery postcode (NL, BE, DE). Affects nothing in the demo but is echoed."},"required":false,"description":"Delivery postcode (NL, BE, DE). Affects nothing in the demo but is echoed.","name":"postcode","in":"query"},{"schema":{"type":"string","enum":["score","price","delivery","return_rate"],"default":"score"},"required":false,"name":"sort","in":"query"},{"schema":{"type":["object","null"],"properties":{"price":{"type":"number","minimum":0,"maximum":1},"delivery":{"type":"number","minimum":0,"maximum":1},"quality":{"type":"number","minimum":0,"maximum":1},"reliability":{"type":"number","minimum":0,"maximum":1}},"description":"Optional ranking weights (each 0 to 1, normalised to sum to 1). Default: price 0.35, delivery 0.25, quality 0.25, reliability 0.15."},"required":false,"description":"Optional ranking weights (each 0 to 1, normalised to sum to 1). Default: price 0.35, delivery 0.25, quality 0.25, reliability 0.15.","name":"weights","in":"query"}],"responses":{"200":{"description":"Search results, excluded list and ranking policy","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"VALIDATION_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{sku}":{"get":{"summary":"Full product (public)","parameters":[{"schema":{"type":"string"},"required":true,"name":"sku","in":"path"},{"schema":{"type":"string"},"required":false,"name":"device","in":"query"},{"schema":{"type":"string"},"required":false,"name":"deliver_by","in":"query"},{"schema":{"type":"string"},"required":false,"name":"weights","in":"query"}],"responses":{"200":{"description":"Specs claimed vs measured, compatibility, ranked offers with score breakdown, performance","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/devices":{"get":{"summary":"Resolve a device from free text (public)","parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Candidates with confidence 0 to 1","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}}}}},"/devices/{slug}/compatible":{"get":{"summary":"Verified parts for a device (public)","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"part_type","in":"query"}],"responses":{"200":{"description":"Parts grouped by part type plus excluded[] with reasons","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compatibility/check":{"post":{"summary":"Fit status for one SKU on one device","security":[{"agentKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","minLength":3,"maxLength":20},"device":{"type":"string","minLength":1,"maxLength":100,"description":"Device slug."}},"required":["sku","device"]}}}},"responses":{"200":{"description":"fit_status, evidence, measured deltas","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions":{"post":{"summary":"Ask a question about a product","security":[{"agentKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","minLength":3,"maxLength":20},"question":{"type":"string","minLength":5,"maxLength":400,"description":"A specific question about this product; answered only from Vera's measured data."}},"required":["sku","question"]}}}},"responses":{"200":{"description":"Answer grounded in measured data","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mandates/current":{"get":{"summary":"Limits and remaining budget","security":[{"agentKey":[]}],"responses":{"200":{"description":"Mandate view","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"MANDATE_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"post":{"summary":"Quote, valid 10 minutes","security":[{"agentKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","minLength":3,"maxLength":20,"description":"Vera SKU to buy."},"quantity":{"type":"integer","minimum":1,"maximum":10,"default":1},"offer_id":{"type":"string","maxLength":60,"description":"Specific offer id. Omit to take the top-ranked eligible offer."},"device":{"type":"string","maxLength":100,"description":"Device slug the part is for. Recommended: the order then carries the fit status and the Right-Item Guarantee."},"postcode":{"type":"string","maxLength":12},"deliver_by":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Latest acceptable delivery date; offers that miss it are not quoted."},"weights":{"type":"object","properties":{"price":{"type":"number","minimum":0,"maximum":1},"delivery":{"type":"number","minimum":0,"maximum":1},"quality":{"type":"number","minimum":0,"maximum":1},"reliability":{"type":"number","minimum":0,"maximum":1}},"description":"Optional ranking weights (each 0 to 1, normalised to sum to 1). Default: price 0.35, delivery 0.25, quality 0.25, reliability 0.15."}},"required":["sku"]}}}},"responses":{"201":{"description":"Quote with exact total and delivery date","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"OUT_OF_STOCK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"summary":"Place an order","description":"Requires Idempotency-Key. Checked against the mandate: category, per-order limit, monthly limit, confirm-above threshold.","security":[{"agentKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","minLength":3,"maxLength":40,"description":"Quote id from get_quote (valid 10 minutes)."},"reason":{"type":"string","minLength":20,"maxLength":500,"description":"Why this item and offer, in 20 to 500 characters. Shown to the user on the receipt."},"mandate_id":{"type":"string","maxLength":40,"description":"Mandate to charge against. Omit to use the active mandate of the user you act for."}},"required":["quote_id","reason"]}}}},"responses":{"201":{"description":"Order placed","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"202":{"description":"CONFIRMATION_REQUIRED: a human must approve","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"IDEMPOTENCY_KEY_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"MANDATE_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"QUOTE_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"CATEGORY_NOT_ALLOWED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"summary":"Order status and timeline","security":[{"agentKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Order view","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel before shipping","security":[{"agentKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Cancelled order","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ORDER_NOT_CANCELLABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/returns":{"post":{"summary":"Start a return (Right-Item Guarantee)","security":[{"agentKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","minLength":3,"maxLength":40},"reason_code":{"type":"string","enum":["wrong_item","does_not_fit","defective","damaged_in_transit","no_longer_needed"],"description":"Use wrong_item or does_not_fit when the part is wrong for the device: the Right-Item Guarantee then refunds instantly."},"note":{"type":"string","maxLength":400}},"required":["order_id","reason_code"]}}}},"responses":{"201":{"description":"Return with refund status, label and suggested replacement","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"AGENT_UNIDENTIFIED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"ORDER_NOT_RETURNABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"RETURN_WINDOW_CLOSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/confirmations/{id}":{"get":{"summary":"Confirmation details (signed link)","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Item, price, agent, reason","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"CONFIRMATION_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Approve or decline","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","decline"]},"token":{"type":"string","minLength":8}},"required":["decision"]}}}},"responses":{"200":{"description":"Decision applied","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"CONFIRMATION_INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"CONFIRMATION_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}