{
  "openapi": "3.1.0",
  "info": {
    "title": "Tethered Trust API",
    "version": "0.5.0",
    "summary": "Compatibility decisions for shopping agents: validate a purchase plan before recommending or ordering.",
    "description": "Every decision is one of supported, conditional, incompatible or insufficient_evidence, with evidence, the exact questions blocking a decision, and a signed receipt. Use the sandbox server while integrating: free, unmetered, never charged. MCP: https://tetheredtrust.com/mcp. Guide: https://tetheredtrust.com/llms.txt.",
    "contact": {
      "name": "Chimes In LLC",
      "email": "support@chimes-in.com",
      "url": "https://tetheredtrust.com/support"
    },
    "termsOfService": "https://tetheredtrust.com/api-terms"
  },
  "servers": [
    {
      "url": "https://tetheredtrust.com/v1",
      "description": "Production (free during early access, within limits)"
    },
    {
      "url": "https://tetheredtrust.com/v1/sandbox",
      "description": "Sandbox: same engine and catalog, free, unmetered, never charged"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Optional during early access: tt_... keys raise limits and are required for prepaid credits."
      }
    }
  },
  "security": [
    {},
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/plan": {
      "post": {
        "summary": "Validate a whole purchase plan (setup + cart)",
        "operationId": "validatePurchasePlan",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "purchase"
                ],
                "properties": {
                  "goal": {
                    "type": "string",
                    "description": "Optional: what the person is trying to do, e.g. 'upgrade this laptop to 32 GB'. Echoed back; requirements are derived from the devices."
                  },
                  "setup": {
                    "type": "array",
                    "maxItems": 24,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "description": "Exact model number or name."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "text": {
                              "type": "string",
                              "description": "Exact model number or name, or key specs."
                            },
                            "id": {
                              "type": "string",
                              "description": "Exact product id (from resolve_product or a question's options)."
                            },
                            "quantity": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 16
                            },
                            "for": {
                              "type": [
                                "string",
                                "integer"
                              ],
                              "description": "Purchases only: which item this part is for (index or name), when the plan has several devices."
                            },
                            "config": {
                              "type": "object",
                              "description": "Setup items only: current configuration, e.g. {\"memory_modules\": [{\"capacity_gb\": 8}], \"installed_drives\": 1, \"replace_memory\": true}."
                            }
                          }
                        }
                      ]
                    },
                    "description": "What the person already owns (devices, appliances, tools, hubs) with exact model numbers, plus current configuration."
                  },
                  "purchase": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "description": "Exact model number or name."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "text": {
                              "type": "string",
                              "description": "Exact model number or name, or key specs."
                            },
                            "id": {
                              "type": "string",
                              "description": "Exact product id (from resolve_product or a question's options)."
                            },
                            "quantity": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 16
                            },
                            "for": {
                              "type": [
                                "string",
                                "integer"
                              ],
                              "description": "Purchases only: which item this part is for (index or name), when the plan has several devices."
                            },
                            "config": {
                              "type": "object",
                              "description": "Setup items only: current configuration, e.g. {\"memory_modules\": [{\"capacity_gb\": 8}], \"installed_drives\": 1, \"replace_memory\": true}."
                            }
                          }
                        }
                      ]
                    },
                    "description": "Everything being considered for purchase: parts, accessories or new devices, with quantities."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plan_id",
                    "decision",
                    "summary",
                    "results"
                  ],
                  "properties": {
                    "plan_id": {
                      "type": "string"
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "supported",
                        "conditional",
                        "incompatible",
                        "insufficient_evidence"
                      ]
                    },
                    "summary": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "item": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "target": {},
                          "decision": {
                            "type": "string",
                            "enum": [
                              "supported",
                              "conditional",
                              "incompatible",
                              "insufficient_evidence"
                            ]
                          },
                          "summary": {
                            "type": "string"
                          },
                          "checks": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "rule": {
                                  "type": "string"
                                },
                                "ok": {
                                  "type": [
                                    "boolean",
                                    "null"
                                  ]
                                },
                                "detail": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          "caveats": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "conditions": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "system_checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "item": {
                            "type": "integer"
                          },
                          "rule": {
                            "type": "string"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "required_accessories": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "substitutions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ask": {
                            "type": "string"
                          },
                          "blocking": {
                            "type": "boolean"
                          },
                          "answer_with": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "requirements": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "confidence": {
                      "type": "number"
                    },
                    "valid_until": {
                      "type": "string"
                    },
                    "receipt": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "next_step": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/plans/recheck": {
      "post": {
        "summary": "Recheck a saved plan against today's data",
        "operationId": "recheckPlan",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id"
                ],
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "description": "The plan_id from validate_purchase_plan."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/plans/{plan_id}": {
      "get": {
        "summary": "Get a saved plan and its receipt status",
        "operationId": "getPlan",
        "parameters": [
          {
            "name": "plan_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Unknown plan_id"
          }
        }
      }
    },
    "/check": {
      "post": {
        "summary": "Check one part against one device",
        "operationId": "checkCompatibility",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "existing",
                  "candidate"
                ],
                "properties": {
                  "existing": {
                    "type": "string",
                    "description": "What the person already has, ideally with the exact model number, e.g. 'Lenovo ThinkPad T480', 'Sony A7 IV', 'DeWalt DCD791', 'HP OfficeJet Pro 9015e', 'iPhone 16 Pro', 'HomePod mini'."
                  },
                  "candidate": {
                    "type": "string",
                    "description": "What they want to buy: a model/part number or key specs, e.g. 'Crucial CT16G4SFRA32A', '1TB M.2 2230 NVMe', 'DCB205', 'HP 962XL', 'Canon RF 24-105mm f/4L', 'Eve Energy'."
                  },
                  "detail": {
                    "type": "string",
                    "description": "Optional extra identifiers: machine type, revision, year, region, serial range."
                  },
                  "existing_id": {
                    "type": "string",
                    "description": "Optional: an exact product id (from resolve_product, suggestions or a candidates list) instead of existing text."
                  },
                  "candidate_id": {
                    "type": "string",
                    "description": "Optional: an exact product id instead of candidate text."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "check_id",
                    "verdict",
                    "confidence",
                    "summary"
                  ],
                  "properties": {
                    "check_id": {
                      "type": "string"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "compatible",
                        "compatible_with_caveats",
                        "incompatible",
                        "uncertain",
                        "needs_detail"
                      ]
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "supported",
                        "conditional",
                        "incompatible",
                        "insufficient_evidence"
                      ],
                      "description": "supported | conditional | incompatible | insufficient_evidence. Act on this, not on confidence alone."
                    },
                    "decision_help": {
                      "type": "string"
                    },
                    "conditions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "What must be true for a conditional answer (accessory, dependency)."
                    },
                    "required_accessories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "why": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ask": {
                            "type": "string"
                          },
                          "blocking": {
                            "type": "boolean"
                          },
                          "answer_with": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      },
                      "description": "Exactly what to ask, measure or look up next. blocking=true means no decision until answered."
                    },
                    "constraints": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "value": {}
                        }
                      }
                    },
                    "candidates": {
                      "type": "object",
                      "description": "Present when the text matched several models: each option with its own verdict."
                    },
                    "fit": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "confidence": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "verified": {
                      "type": "boolean",
                      "description": "True only when every spec came from reviewed manufacturer sources."
                    },
                    "summary": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rule": {
                            "type": "string"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "caveats": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requirements": {
                      "type": "object"
                    },
                    "missing": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "next_step": {
                      "type": "string"
                    },
                    "valid_until": {
                      "type": "string",
                      "description": "When this answer should be re-checked (based on how fresh its sources are)."
                    },
                    "receipt": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Signed receipt (EdDSA JWS) proving Tethered Trust issued this verdict unaltered. Not a guarantee the verdict is correct.",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "jws": {
                          "type": "string"
                        },
                        "valid_until": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    },
                    "notice": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/check/batch": {
      "post": {
        "summary": "Up to 25 checks in one call",
        "operationId": "checkBatch",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "checks"
                ],
                "properties": {
                  "checks": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "items": {
                      "type": "object",
                      "required": [
                        "existing",
                        "candidate"
                      ],
                      "properties": {
                        "existing": {
                          "type": "string",
                          "description": "What the person already has, ideally with the exact model number, e.g. 'Lenovo ThinkPad T480', 'Sony A7 IV', 'DeWalt DCD791', 'HP OfficeJet Pro 9015e', 'iPhone 16 Pro', 'HomePod mini'."
                        },
                        "candidate": {
                          "type": "string",
                          "description": "What they want to buy: a model/part number or key specs, e.g. 'Crucial CT16G4SFRA32A', '1TB M.2 2230 NVMe', 'DCB205', 'HP 962XL', 'Canon RF 24-105mm f/4L', 'Eve Energy'."
                        },
                        "detail": {
                          "type": "string",
                          "description": "Optional extra identifiers: machine type, revision, year, region, serial range."
                        },
                        "existing_id": {
                          "type": "string",
                          "description": "Optional: an exact product id (from resolve_product, suggestions or a candidates list) instead of existing text."
                        },
                        "candidate_id": {
                          "type": "string",
                          "description": "Optional: an exact product id instead of candidate text."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/parts": {
      "post": {
        "summary": "List parts that fit a model",
        "operationId": "findParts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model"
                ],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Model number of the device, tool, camera, printer or appliance, e.g. 'GFE28GYNFS', 'ThinkPad T480', 'Canon EOS R6 Mark II', 'Milwaukee 2904-20', 'Brother HL-L2350DW'."
                  },
                  "part_type": {
                    "type": "string",
                    "description": "Optional filter, e.g. 'water filter', 'memory', 'ssd', 'charger', 'battery', 'lens', 'ink', 'toner', 'band'."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "check_id",
                    "found",
                    "parts",
                    "message"
                  ],
                  "properties": {
                    "check_id": {
                      "type": "string"
                    },
                    "found": {
                      "type": "boolean"
                    },
                    "model": {},
                    "total": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    },
                    "parts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "part_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "part_type": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          },
                          "verified": {
                            "type": "boolean"
                          },
                          "note": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "caveats": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "source_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "notice": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/fit": {
      "post": {
        "summary": "Physical fit of an appliance in a space",
        "operationId": "checkFit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "opening"
                ],
                "properties": {
                  "product": {
                    "type": "string",
                    "description": "What's being installed, e.g. '36-inch French-door refrigerator'. Used to pick typical clearances."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "refrigerator",
                      "dishwasher",
                      "range",
                      "washer",
                      "dryer",
                      "other"
                    ]
                  },
                  "product_dimensions": {
                    "type": "object",
                    "description": "Width, height and depth of the product (from its spec sheet). Any subset is accepted; missing axes come back as 'missing'.",
                    "properties": {
                      "width": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      },
                      "height": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      },
                      "depth": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      }
                    }
                  },
                  "opening": {
                    "type": "object",
                    "description": "Width, height and depth of the space it goes into. Any subset is accepted; missing axes come back as 'missing'.",
                    "properties": {
                      "width": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      },
                      "height": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      },
                      "depth": {
                        "type": "string",
                        "description": "A number in inches (e.g. \"35.75\") or text with units (\"35 3/4 in\", \"90.8 cm\", \"908 mm\")."
                      }
                    }
                  },
                  "needs": {
                    "type": "string",
                    "description": "Connections the product needs, e.g. '120V, water line' or '240V'."
                  },
                  "has": {
                    "type": "string",
                    "description": "Connections available at the location."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "check_id",
                    "verdict",
                    "confidence",
                    "summary"
                  ],
                  "properties": {
                    "check_id": {
                      "type": "string"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "compatible",
                        "compatible_with_caveats",
                        "incompatible",
                        "uncertain",
                        "needs_detail"
                      ]
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "supported",
                        "conditional",
                        "incompatible",
                        "insufficient_evidence"
                      ],
                      "description": "supported | conditional | incompatible | insufficient_evidence. Act on this, not on confidence alone."
                    },
                    "decision_help": {
                      "type": "string"
                    },
                    "conditions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "What must be true for a conditional answer (accessory, dependency)."
                    },
                    "required_accessories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "why": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ask": {
                            "type": "string"
                          },
                          "blocking": {
                            "type": "boolean"
                          },
                          "answer_with": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      },
                      "description": "Exactly what to ask, measure or look up next. blocking=true means no decision until answered."
                    },
                    "constraints": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "value": {}
                        }
                      }
                    },
                    "candidates": {
                      "type": "object",
                      "description": "Present when the text matched several models: each option with its own verdict."
                    },
                    "fit": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "confidence": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "verified": {
                      "type": "boolean",
                      "description": "True only when every spec came from reviewed manufacturer sources."
                    },
                    "summary": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rule": {
                            "type": "string"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "caveats": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requirements": {
                      "type": "object"
                    },
                    "missing": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "next_step": {
                      "type": "string"
                    },
                    "valid_until": {
                      "type": "string",
                      "description": "When this answer should be re-checked (based on how fresh its sources are)."
                    },
                    "receipt": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Signed receipt (EdDSA JWS) proving Tethered Trust issued this verdict unaltered. Not a guarantee the verdict is correct.",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "jws": {
                          "type": "string"
                        },
                        "valid_until": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    },
                    "notice": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/resolve": {
      "get": {
        "summary": "Identify a product (returns candidates when ambiguous)",
        "operationId": "resolveProduct",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Model number or name",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "found"
                  ],
                  "properties": {
                    "found": {
                      "type": "boolean"
                    },
                    "ambiguous": {
                      "type": "boolean"
                    },
                    "product": {
                      "type": "object"
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "read_from_text": {},
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/suggest": {
      "get": {
        "summary": "Type-ahead product suggestions",
        "operationId": "suggest",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Text typed so far (2+ characters)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "any | host | part",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "1-20",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/coverage": {
      "get": {
        "summary": "Categories and models covered",
        "operationId": "listCoverage",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional category id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "categories",
                    "totals"
                  ],
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "totals": {
                      "type": "object"
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/receipts/verify": {
      "post": {
        "summary": "Verify a signed receipt",
        "operationId": "verifyReceipt",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "receipt_id": {
                    "type": "string",
                    "description": "The receipt id (rcpt_...) from a check."
                  },
                  "jws": {
                    "type": "string",
                    "description": "Or the full signed receipt string, if someone handed it to you."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "signature_valid",
                    "status"
                  ],
                  "properties": {
                    "signature_valid": {
                      "type": "boolean"
                    },
                    "issued_by_tethered_trust": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "valid",
                        "expired",
                        "revoked",
                        "data_changed",
                        "invalid_signature",
                        "unknown_key"
                      ]
                    },
                    "explain": {
                      "type": "string"
                    },
                    "receipt_id": {
                      "type": "string"
                    },
                    "claim": {
                      "type": "object"
                    },
                    "issued_at": {
                      "type": "string"
                    },
                    "valid_until": {
                      "type": "string"
                    },
                    "changed_subjects": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/receipts/{receipt_id}": {
      "get": {
        "summary": "Get a receipt and its current status",
        "operationId": "getReceipt",
        "parameters": [
          {
            "name": "receipt_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/outcome": {
      "post": {
        "summary": "Report what happened after a purchase",
        "operationId": "reportOutcome",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "check_id",
                  "outcome"
                ],
                "properties": {
                  "check_id": {
                    "type": "string",
                    "description": "The check_id returned by check_compatibility, find_parts or check_fit."
                  },
                  "outcome": {
                    "type": "string",
                    "enum": [
                      "fit",
                      "no_fit"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "description": "What happened, briefly."
                  },
                  "evidence": {
                    "type": "object",
                    "description": "Optional order details we can confirm later (raises the report to 'order_confirmed' once reviewed). Don't include payment or personal details.",
                    "properties": {
                      "order_id": {
                        "type": "string"
                      },
                      "merchant": {
                        "type": "string"
                      },
                      "purchased_at": {
                        "type": "string"
                      },
                      "delivered_at": {
                        "type": "string"
                      },
                      "returned_at": {
                        "type": "string"
                      },
                      "product_url": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "recorded",
                    "message"
                  ],
                  "properties": {
                    "recorded": {
                      "type": "boolean"
                    },
                    "level": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "self_reported",
                        "agent_reported",
                        "partner_reported",
                        "order_confirmed",
                        null
                      ]
                    },
                    "evidence_received": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/usage": {
      "get": {
        "summary": "Usage and credit balance for your API key",
        "operationId": "usage",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Send an API key"
          }
        }
      }
    },
    "/paid/plan": {
      "post": {
        "summary": "Paid: validate a purchase plan ($0.25 per completed decision)",
        "operationId": "paidValidatePurchasePlan",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "purchase"
                ],
                "properties": {
                  "goal": {
                    "type": "string",
                    "description": "Optional: what the person is trying to do, e.g. 'upgrade this laptop to 32 GB'. Echoed back; requirements are derived from the devices."
                  },
                  "setup": {
                    "type": "array",
                    "maxItems": 24,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "description": "Exact model number or name."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "text": {
                              "type": "string",
                              "description": "Exact model number or name, or key specs."
                            },
                            "id": {
                              "type": "string",
                              "description": "Exact product id (from resolve_product or a question's options)."
                            },
                            "quantity": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 16
                            },
                            "for": {
                              "type": [
                                "string",
                                "integer"
                              ],
                              "description": "Purchases only: which item this part is for (index or name), when the plan has several devices."
                            },
                            "config": {
                              "type": "object",
                              "description": "Setup items only: current configuration, e.g. {\"memory_modules\": [{\"capacity_gb\": 8}], \"installed_drives\": 1, \"replace_memory\": true}."
                            }
                          }
                        }
                      ]
                    },
                    "description": "What the person already owns (devices, appliances, tools, hubs) with exact model numbers, plus current configuration."
                  },
                  "purchase": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 25,
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "description": "Exact model number or name."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "text": {
                              "type": "string",
                              "description": "Exact model number or name, or key specs."
                            },
                            "id": {
                              "type": "string",
                              "description": "Exact product id (from resolve_product or a question's options)."
                            },
                            "quantity": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 16
                            },
                            "for": {
                              "type": [
                                "string",
                                "integer"
                              ],
                              "description": "Purchases only: which item this part is for (index or name), when the plan has several devices."
                            },
                            "config": {
                              "type": "object",
                              "description": "Setup items only: current configuration, e.g. {\"memory_modules\": [{\"capacity_gb\": 8}], \"installed_drives\": 1, \"replace_memory\": true}."
                            }
                          }
                        }
                      ]
                    },
                    "description": "Everything being considered for purchase: parts, accessories or new devices, with quantities."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plan_id",
                    "decision",
                    "summary",
                    "results"
                  ],
                  "properties": {
                    "plan_id": {
                      "type": "string"
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "supported",
                        "conditional",
                        "incompatible",
                        "insufficient_evidence"
                      ]
                    },
                    "summary": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "item": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "target": {},
                          "decision": {
                            "type": "string",
                            "enum": [
                              "supported",
                              "conditional",
                              "incompatible",
                              "insufficient_evidence"
                            ]
                          },
                          "summary": {
                            "type": "string"
                          },
                          "checks": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "rule": {
                                  "type": "string"
                                },
                                "ok": {
                                  "type": [
                                    "boolean",
                                    "null"
                                  ]
                                },
                                "detail": {
                                  "type": "string"
                                }
                              }
                            }
                          },
                          "caveats": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "conditions": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "system_checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "item": {
                            "type": "integer"
                          },
                          "rule": {
                            "type": "string"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "required_accessories": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "substitutions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ask": {
                            "type": "string"
                          },
                          "blocking": {
                            "type": "boolean"
                          },
                          "answer_with": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    },
                    "requirements": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "confidence": {
                      "type": "number"
                    },
                    "valid_until": {
                      "type": "string"
                    },
                    "receipt": {
                      "type": [
                        "object",
                        "null"
                      ]
                    },
                    "next_step": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    },
    "/paid/check": {
      "post": {
        "summary": "Paid: one check ($0.05 per completed answer)",
        "operationId": "paidCheck",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "existing",
                  "candidate"
                ],
                "properties": {
                  "existing": {
                    "type": "string",
                    "description": "What the person already has, ideally with the exact model number, e.g. 'Lenovo ThinkPad T480', 'Sony A7 IV', 'DeWalt DCD791', 'HP OfficeJet Pro 9015e', 'iPhone 16 Pro', 'HomePod mini'."
                  },
                  "candidate": {
                    "type": "string",
                    "description": "What they want to buy: a model/part number or key specs, e.g. 'Crucial CT16G4SFRA32A', '1TB M.2 2230 NVMe', 'DCB205', 'HP 962XL', 'Canon RF 24-105mm f/4L', 'Eve Energy'."
                  },
                  "detail": {
                    "type": "string",
                    "description": "Optional extra identifiers: machine type, revision, year, region, serial range."
                  },
                  "existing_id": {
                    "type": "string",
                    "description": "Optional: an exact product id (from resolve_product, suggestions or a candidates list) instead of existing text."
                  },
                  "candidate_id": {
                    "type": "string",
                    "description": "Optional: an exact product id instead of candidate text."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "check_id",
                    "verdict",
                    "confidence",
                    "summary"
                  ],
                  "properties": {
                    "check_id": {
                      "type": "string"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "compatible",
                        "compatible_with_caveats",
                        "incompatible",
                        "uncertain",
                        "needs_detail"
                      ]
                    },
                    "decision": {
                      "type": "string",
                      "enum": [
                        "supported",
                        "conditional",
                        "incompatible",
                        "insufficient_evidence"
                      ],
                      "description": "supported | conditional | incompatible | insufficient_evidence. Act on this, not on confidence alone."
                    },
                    "decision_help": {
                      "type": "string"
                    },
                    "conditions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "What must be true for a conditional answer (accessory, dependency)."
                    },
                    "required_accessories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "why": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "questions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ask": {
                            "type": "string"
                          },
                          "blocking": {
                            "type": "boolean"
                          },
                          "answer_with": {
                            "type": "string"
                          },
                          "options": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      },
                      "description": "Exactly what to ask, measure or look up next. blocking=true means no decision until answered."
                    },
                    "constraints": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "value": {}
                        }
                      }
                    },
                    "candidates": {
                      "type": "object",
                      "description": "Present when the text matched several models: each option with its own verdict."
                    },
                    "fit": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "confidence": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "verified": {
                      "type": "boolean",
                      "description": "True only when every spec came from reviewed manufacturer sources."
                    },
                    "summary": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rule": {
                            "type": "string"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "caveats": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requirements": {
                      "type": "object"
                    },
                    "missing": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "evidence": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          },
                          "url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "next_step": {
                      "type": "string"
                    },
                    "valid_until": {
                      "type": "string",
                      "description": "When this answer should be re-checked (based on how fresh its sources are)."
                    },
                    "receipt": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Signed receipt (EdDSA JWS) proving Tethered Trust issued this verdict unaltered. Not a guarantee the verdict is correct.",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "jws": {
                          "type": "string"
                        },
                        "valid_until": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    },
                    "notice": {
                      "type": "string"
                    },
                    "terms": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input. The body has an `error` message saying what to send."
          },
          "402": {
            "description": "Payment required (paid endpoints, or the free allowance is used up). Includes x402 PaymentRequired and a credits link."
          },
          "429": {
            "description": "Rate limit reached for this hour."
          }
        }
      }
    }
  }
}