{"openapi":"3.1.0","info":{"title":"KEVAREMESH Capability Gateway","version":"0.5.21","description":"Buyer-side AI/API procurement and x402 payment relay. KEVAREMESH automatically discovers, selects and adapts upstream supply. KEVAREMESH charges a success-triggered $0.001 24-hour Access Pass on the first successful routed job when no active pass exists; no additional KEVAREMESH gateway fee applies while the pass is active."},"servers":[{"url":"https://kevaremesh-web.vercel.app/api/x402/gateway"}],"paths":{"/health":{"get":{"summary":"Gateway readiness and catalog health","security":[],"responses":{"200":{"description":"Gateway and market database ready"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}},"/catalog":{"get":{"summary":"Free discovery of route-eligible capability supply","security":[],"responses":{"200":{"description":"Capability supply catalog"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}},"/quote":{"post":{"summary":"Free route plan and fee estimate","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["capability"],"properties":{"capability":{"type":"string","description":"KEVAREMESH capability cluster such as web_search or llm_inference"},"goal":{"type":"string","maxLength":500,"description":"Optional buyer objective used only to rank providers within the capability. Raw goal is not stored in route metadata."},"resource":{"type":"string","format":"uri","description":"Optional exact provider resource selected during a prior free quote. When supplied, KEVAREMESH will not silently substitute a different provider."},"quantity":{"type":"integer","minimum":1,"maximum":1000,"default":1},"max_unit_price_usd":{"type":"number","minimum":0},"min_unique_payers_30d":{"type":"integer","minimum":0},"request":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"default":"POST"},"query":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"body":{}},"additionalProperties":false},"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"default":"POST"},"query":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"body":{}},"additionalProperties":false}}}}},"preference":{"type":"string","enum":["balanced","cheapest","proven"],"default":"balanced"},"max_total_upstream_usd":{"type":"number","minimum":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"Route quote"},"422":{"description":"Invalid request"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}},"/":{"post":{"summary":"Free route preparation and upstream x402 challenge collection","description":"Selects eligible providers, probes them without payment, captures their current x402 challenges, and creates short-lived execution tokens. No KEVAREMESH payment is charged during route preparation. A $0.001 24-hour Access Pass is requested only after a successful routed job if the client has no active pass.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["capability"],"properties":{"capability":{"type":"string","description":"KEVAREMESH capability cluster such as web_search or llm_inference"},"goal":{"type":"string","maxLength":500,"description":"Optional buyer objective used only to rank providers within the capability. Raw goal is not stored in route metadata."},"resource":{"type":"string","format":"uri","description":"Optional exact provider resource selected during a prior free quote. When supplied, KEVAREMESH will not silently substitute a different provider."},"quantity":{"type":"integer","minimum":1,"maximum":1000,"default":1},"max_unit_price_usd":{"type":"number","minimum":0},"min_unique_payers_30d":{"type":"integer","minimum":0},"request":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"default":"POST"},"query":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"body":{}},"additionalProperties":false},"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"default":"POST"},"query":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"body":{}},"additionalProperties":false}}}}},"preference":{"type":"string","enum":["balanced","cheapest","proven"],"default":"balanced"},"max_total_upstream_usd":{"type":"number","minimum":0}},"additionalProperties":false}}}},"responses":{"200":{"description":"Prepared route and upstream payment challenges"},"422":{"description":"Invalid request"},"502":{"description":"No executable upstream candidate"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}},"/execute":{"post":{"summary":"Execute one selected upstream x402 request","description":"No KEVAREMESH fee. First call returns the selected Provider's standard x402 challenge. The buyer pays that Provider directly and retries. Successful provider results are released through finalization; the first successful routed job may require the $0.001 24-hour Access Pass, and later finalizations are free while the pass is active.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["execution_token","request"],"properties":{"execution_token":{"type":"string","minLength":20},"request":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST"],"default":"POST"},"query":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"body":{}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Upstream succeeded; result is ready for finalization"},"402":{"description":"Selected upstream Provider payment required"},"409":{"description":"Execution token invalid, expired, used, or request mismatch"},"422":{"description":"Invalid request"},"502":{"description":"Upstream execution failed"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}},"/finalize":{"post":{"summary":"Receive successful procurement results","description":"Available only after all prepared upstream executions succeeded. If the client has no active Access Pass, the first successful routed job requests a one-time $0.001 24-hour Access Pass payment; otherwise finalization is free.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gateway_request_id","finalize_token"],"properties":{"gateway_request_id":{"type":"string","format":"uuid"},"finalize_token":{"type":"string","minLength":20}},"additionalProperties":false}}}},"responses":{"200":{"description":"Final provider results","content":{"application/json":{"schema":{"type":"object","required":["service","product","gateway_request_id","job_success","gateway_payment_settled","gateway_fee_usd","results"],"properties":{"service":{"type":"string"},"product":{"type":"string"},"gateway_request_id":{"type":"string","format":"uuid"},"job_success":{"type":"boolean"},"gateway_payment_settled":{"type":"boolean"},"gateway_fee_usd":{"type":"number"},"upstream_execution_count":{"type":"integer"},"results":{"type":"array","items":{"type":"object"}},"generated_at":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"KEVAREMESH gateway payment required"},"409":{"description":"Job has not successfully completed"},"422":{"description":"Invalid request"},"502":{"description":"Finalization failed"},"503":{"description":"Temporary database unavailability; retry according to Retry-After.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1,"example":30}}},"content":{"application/json":{"schema":{"type":"object","required":["error","retryable"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string","example":"database_temporarily_unavailable"},"retryable":{"type":"boolean","const":true}}}}}}}}}}}