{"openapi":"3.1.0","info":{"title":"TaskRail Practical Agent Utilities API","version":"1.3.1","description":"Four accountless, pay-per-call x402 tools: find the cheapest delivered product price, the fastest official completion path, worthwhile used or refurbished alternatives, and whether exact products are compatible."},"servers":[{"url":"https://taskrail.alamavar.com"}],"paths":{"/health":{"get":{"operationId":"health","responses":{"200":{"description":"Healthy"}}}},"/status":{"get":{"operationId":"status","responses":{"200":{"description":"Public status"}}}},"/v1/capabilities":{"get":{"operationId":"capabilities","responses":{"200":{"description":"Capabilities"}}}},"/v1/examples":{"get":{"operationId":"requestExamples","responses":{"200":{"description":"Copy-ready free quote and paid request examples"}}}},"/v1/demo/deals-new":{"get":{"operationId":"liveBestDealSample","description":"Run a free, fixed-input live sample. Source-funded cache misses are capped globally at three per UTC day; cached sample responses remain free.","responses":{"200":{"description":"Live or cached sample result; buyer charge is zero"},"429":{"description":"Daily live-sample retrieval budget exhausted","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/v1/quote":{"post":{"operationId":"quote","responses":{"200":{"description":"Fixed price quote"}}}},"/v1/receipts/{orderId}":{"get":{"operationId":"receipt","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"string","minLength":16,"maxLength":128}}],"responses":{"200":{"description":"Scoped x402 payment receipt"},"404":{"description":"Receipt not found","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/v1/retry":{"post":{"operationId":"retryWithEntitlement","description":"Consume a signed, single-use retry entitlement without placing the capability token in a URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entitlementToken":{"type":"string","minLength":64,"maxLength":4096}},"required":["entitlementToken"],"additionalProperties":false}}}},"responses":{"202":{"description":"Retry accepted without additional payment"},"409":{"description":"Entitlement already used","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/mcp":{"post":{"operationId":"mcp","description":"MCP Streamable HTTP endpoint","responses":{"200":{"description":"MCP response"}}}},"/v1/deals/new/standard":{"post":{"operationId":"_v1_deals_new_standard","summary":"Find the cheapest price, best deal, and where to buy an exact new product, including shipping, stock, and known total cost.","tags":["deals-new"],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16}},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 v2 signed payment proof supplied after the initial 402."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product":{"type":"string","minLength":2,"maxLength":500,"description":"Exact product name, model, and variant in the user's own words"},"postal_code":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"US postal code for delivery price and availability"}},"required":["product"],"additionalProperties":false}}}},"responses":{"200":{"description":"Fulfilled and settled result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"order_id":{"type":"string"},"status":{"type":"string"},"decision":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"best_price_usd":{"type":"number","minimum":0},"sources_checked_count":{"type":"integer","minimum":0},"data":{"type":"object"},"sources_checked":{"type":"array","items":{"type":"string"}},"sources_failed":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","items":{"type":"object"}},"freshness":{"type":"object"},"coverage":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object"},"payment":{"type":"object"}},"required":["request_id","order_id","status","decision","recommendation","confidence","sources_checked_count","data","sources_checked","sources_failed","provenance","freshness","coverage","limitations","usage"]}}}},"402":{"description":"x402 payment required or settlement failed","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired document."}},"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"503":{"description":"Unavailable or budget-gated before payment","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/v1/tasks/completion-path/standard":{"post":{"operationId":"_v1_tasks_completion_path_standard","summary":"Find the fastest official way to cancel, return an item, get a refund, or reach the correct official form.","tags":["tasks-path"],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16}},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 v2 signed payment proof supplied after the initial 402."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"provider":{"type":"string","minLength":2,"maxLength":200,"description":"Company, agency, service, or organization responsible for the task"},"task":{"type":"string","minLength":2,"maxLength":300,"description":"What the user needs to do, in ordinary language"},"state":{"description":"Optional two-letter US state code when rules or forms vary by state","type":"string","minLength":2,"maxLength":2}},"required":["provider","task"],"additionalProperties":false}}}},"responses":{"200":{"description":"Fulfilled and settled result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"order_id":{"type":"string"},"status":{"type":"string"},"decision":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"best_price_usd":{"type":"number","minimum":0},"sources_checked_count":{"type":"integer","minimum":0},"data":{"type":"object"},"sources_checked":{"type":"array","items":{"type":"string"}},"sources_failed":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","items":{"type":"object"}},"freshness":{"type":"object"},"coverage":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object"},"payment":{"type":"object"}},"required":["request_id","order_id","status","decision","recommendation","confidence","sources_checked_count","data","sources_checked","sources_failed","provenance","freshness","coverage","limitations","usage"]}}}},"402":{"description":"x402 payment required or settlement failed","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired document."}},"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"503":{"description":"Unavailable or budget-gated before payment","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/v1/deals/used/standard":{"post":{"operationId":"_v1_deals_used_standard","summary":"Find used, refurbished, and open-box options for an exact product and decide whether the cheaper alternative is worth it.","tags":["deals-used"],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16}},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 v2 signed payment proof supplied after the initial 402."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product":{"type":"string","minLength":2,"maxLength":500,"description":"Exact product name, model, and variant to buy used or refurbished"},"postal_code":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"US postal code for delivery price and availability"},"minimum_savings_percent":{"default":15,"description":"Minimum savings that would make a used option worthwhile","type":"number","minimum":0,"maximum":90}},"required":["product","minimum_savings_percent"],"additionalProperties":false}}}},"responses":{"200":{"description":"Fulfilled and settled result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"order_id":{"type":"string"},"status":{"type":"string"},"decision":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"best_price_usd":{"type":"number","minimum":0},"sources_checked_count":{"type":"integer","minimum":0},"data":{"type":"object"},"sources_checked":{"type":"array","items":{"type":"string"}},"sources_failed":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","items":{"type":"object"}},"freshness":{"type":"object"},"coverage":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object"},"payment":{"type":"object"}},"required":["request_id","order_id","status","decision","recommendation","confidence","sources_checked_count","data","sources_checked","sources_failed","provenance","freshness","coverage","limitations","usage"]}}}},"402":{"description":"x402 payment required or settlement failed","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired document."}},"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"503":{"description":"Unavailable or budget-gated before payment","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/v1/compatibility/standard":{"post":{"operationId":"_v1_compatibility_standard","summary":"Check whether exact products fit or work together, whether they are compatible, and whether an adapter is needed.","tags":["compatibility"],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16}},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 v2 signed payment proof supplied after the initial 402."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"primary_product":{"type":"string","minLength":2,"maxLength":500,"description":"The product, device, vehicle, or system the candidate must work with"},"candidate_product":{"type":"string","minLength":2,"maxLength":500,"description":"The accessory, part, consumable, adapter, or component being checked"},"required_use":{"description":"Optional explanation of the intended use","type":"string","maxLength":500},"vehicle_vin":{"description":"Optional 17-character VIN for authoritative NHTSA vehicle identification","type":"string","pattern":"^[A-HJ-NPR-Z0-9]{17}$"}},"required":["primary_product","candidate_product"],"additionalProperties":false}}}},"responses":{"200":{"description":"Fulfilled and settled result","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"order_id":{"type":"string"},"status":{"type":"string"},"decision":{"type":"string"},"recommendation":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"best_price_usd":{"type":"number","minimum":0},"sources_checked_count":{"type":"integer","minimum":0},"data":{"type":"object"},"sources_checked":{"type":"array","items":{"type":"string"}},"sources_failed":{"type":"array","items":{"type":"string"}},"provenance":{"type":"array","items":{"type":"object"}},"freshness":{"type":"object"},"coverage":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"usage":{"type":"object"},"payment":{"type":"object"}},"required":["request_id","order_id","status","decision","recommendation","confidence","sources_checked_count","data","sources_checked","sources_failed","provenance","freshness","coverage","limitations","usage"]}}}},"402":{"description":"x402 payment required or settlement failed","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired document."}},"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"503":{"description":"Unavailable or budget-gated before payment","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}}}}