{"openapi":"3.1.0","info":{"title":"Vendor Finder","version":"1.0.0","description":"Pay-per-search vendor research with evidence. x402 v2 USDC on Base. The Idempotency-Key is also the secret result access token. No subscriptions or vendor transactions."},"servers":[{"url":"https://vendorfinder.online"}],"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"Read configuration and database readiness","responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Unavailable","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","summary":"Read configured prices, candidate limits, mode and payment policy","responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/quote":{"post":{"operationId":"quote","summary":"Validate input and see the current price before paying","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FindRequest"},{"type":"string","minLength":8,"maxLength":4000}]}},"text/plain":{"schema":{"type":"string","minLength":8,"maxLength":4000}}}},"responses":{"200":{"description":"Quote and x402 payment requirements","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"const":"USDC"},"tier":{"type":"string"},"mode":{"enum":["demo","live"]},"network":{"type":"string"},"policy":{"type":"string"},"payment":{"$ref":"#/components/schemas/PaymentRequired"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Not ready; no payment accepted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/find":{"post":{"operationId":"findVendors","summary":"Pay for and receive an evidence-backed vendor shortlist","description":"Send JSON or text/plain, maximum 16 KiB. Normal completion is synchronous. Poll a 202 request using its request_id. Payment settles before research. Reuse the same body and secret key after interruption. Paid provider failures allow two free retries. A zero-match completed search is charged. Do not sign a new payment after settlement_unknown.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Random secret unique to this request. Also used as Bearer token for retrieval.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 v2 EIP-3009 payment payload. Demo only: demo:<Idempotency-Key>.","schema":{"type":"string","maxLength":16000}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FindRequest"},{"type":"string","minLength":8,"maxLength":4000}]}},"text/plain":{"schema":{"type":"string","minLength":8,"maxLength":4000}}}},"responses":{"200":{"description":"Completed shortlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorShortlist"}}},"headers":{"PAYMENT-RESPONSE":{"description":"Base64 settlement receipt","schema":{"type":"string"}}}},"202":{"description":"Existing request in progress","content":{"application/json":{"schema":{"type":"object","required":["request_id","status","paid","retryable"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"enum":["settling","processing","failed","settlement_unknown","payment_failed"]},"paid":{"type":"boolean"},"retryable":{"type":"boolean"},"error":{"type":"object"}}}}}},"400":{"description":"Invalid input or missing Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}},"headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 v2 payment requirements","schema":{"type":"string"}}}},"409":{"description":"Request key conflict or reused payment","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"413":{"description":"Body over 16 KiB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate limited; obey Retry-After","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Provider failure, uncertain settlement or missing configuration","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},{"type":"object","required":["request_id","status","paid","retryable"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"enum":["settling","processing","failed","settlement_unknown","payment_failed"]},"paid":{"type":"boolean"},"retryable":{"type":"boolean"},"error":{"type":"object"}}}]}}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"getRequest","summary":"Retrieve a private result or status","security":[{"ResultAccess":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Completed shortlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorShortlist"}}}},"202":{"description":"Processing","content":{"application/json":{"schema":{"type":"object","required":["request_id","status","paid","retryable"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"enum":["settling","processing","failed","settlement_unknown","payment_failed"]},"paid":{"type":"boolean"},"retryable":{"type":"boolean"},"error":{"type":"object"}}}}}},"401":{"description":"Access key missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Unknown request or wrong key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"503":{"description":"Failed or settlement uncertain","content":{"application/json":{"schema":{"type":"object","required":["request_id","status","paid","retryable"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"enum":["settling","processing","failed","settlement_unknown","payment_failed"]},"paid":{"type":"boolean"},"retryable":{"type":"boolean"},"error":{"type":"object"}}}}}}}}}},"components":{"securitySchemes":{"ResultAccess":{"type":"http","scheme":"bearer","description":"Original Idempotency-Key"}},"schemas":{"FindRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"need":{"type":"string","minLength":8,"maxLength":4000},"category":{"type":"string","minLength":1,"maxLength":500},"requirements":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"location":{"type":"string","minLength":1,"maxLength":500},"service_area":{"type":"string","minLength":1,"maxLength":500},"budget":{"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"quantity":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1000000000000},{"type":"null"}]},"deadline":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"must_have":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"nice_to_have":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"exclude":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"max_results":{"default":5,"type":"integer","minimum":1,"maximum":10},"tier":{"default":"standard","type":"string","enum":["quick","standard","deep"]}},"required":["need","requirements","must_have","nice_to_have","exclude","max_results","tier"],"additionalProperties":false},"VendorShortlist":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"query":{"type":"object","properties":{"need":{"type":"string","minLength":8,"maxLength":4000},"category":{"type":"string","minLength":1,"maxLength":500},"requirements":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"location":{"type":"string","minLength":1,"maxLength":500},"service_area":{"type":"string","minLength":1,"maxLength":500},"budget":{"type":"object","properties":{"min":{"type":"number","minimum":0},"max":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"quantity":{"anyOf":[{"type":"number","exclusiveMinimum":0,"maximum":1000000000000},{"type":"null"}]},"deadline":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"must_have":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"nice_to_have":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"exclude":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"max_results":{"default":5,"type":"integer","minimum":1,"maximum":10},"tier":{"default":"standard","type":"string","enum":["quick","standard","deep"]}},"required":["need","requirements","must_have","nice_to_have","exclude","max_results","tier"],"additionalProperties":false},"status":{"type":"string","const":"completed"},"vendors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"website":{"type":"string","format":"uri"},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"type":"string"},"match_reasons":{"type":"array","items":{"type":"string"}},"requirements_met":{"type":"array","items":{"type":"string"}},"requirements_unverified":{"type":"array","items":{"type":"string"}},"inferred_information":{"type":"array","items":{"type":"string"}},"pricing":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["value","currency","source"],"additionalProperties":false},"contact":{"type":"object","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","phone","contact_url"],"additionalProperties":false},"evidence":{"minItems":1,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"quote":{"type":"string"},"source_type":{"type":"string","enum":["vendor_website","authoritative","demo"]}},"required":["url","title","retrieved_at","quote","source_type"],"additionalProperties":false}},"verified_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["name","website","location","description","match_reasons","requirements_met","requirements_unverified","inferred_information","pricing","contact","evidence","verified_at"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}},"completed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"mode":{"type":"string","enum":["demo","live"]},"price":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string","const":"USDC"},"tier":{"type":"string"}},"required":["amount","currency","tier"],"additionalProperties":false}},"required":["request_id","query","status","vendors","limitations","completed_at","mode","price"],"additionalProperties":false},"PaymentRequired":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"const":2},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","amount","asset","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"const":"exact"},"network":{"enum":["eip155:8453","eip155:84532"]},"amount":{"type":"string","description":"USDC atomic units, 6 decimals"},"asset":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}}}}}}}