{
  "openapi": "3.1.0",
  "info": {
    "title": "FOXIFY Public API",
    "version": "2026-11-19",
    "summary": "Machine-readable contracts for FOXIFY free public REST surfaces.",
    "description": "Canonical first-party contract for the live free Outcome Receipt planner/checker and Basket Repair API. Paid x402 preflights and MCP are separate compatibility adapters documented at foxify.pro/developers and foxify.pro/machine-start.",
    "contact": {
      "email": "contact@foxify.pro",
      "url": "https://foxify.pro/contact/"
    }
  },
  "servers": [
    {
      "url": "https://foxify.pro",
      "description": "Canonical FOXIFY origin"
    }
  ],
  "externalDocs": {
    "description": "FOXIFY developer documentation",
    "url": "https://foxify.pro/developers/"
  },
  "tags": [
    {
      "name": "Outcome Receipt",
      "description": "Plan and structurally verify bounded outcome receipts. No downstream action is executed."
    },
    {
      "name": "Basket Repair",
      "description": "Free bounded basket solver/checker over caller-supplied integer-cent offers."
    },
    {
      "name": "Discovery",
      "description": "Machine-readable FOXIFY capability and contract discovery."
    }
  ],
  "paths": {
    "/.well-known/foxify-services.json": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "FOXIFY machine capability catalog",
        "responses": {
          "200": {
            "description": "Capability catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/outcome/v1/plan": {
      "post": {
        "tags": [
          "Outcome Receipt"
        ],
        "summary": "Create a free bounded outcome check plan",
        "description": "Validates and binds exact intent, target, authority and postconditions. Executes nothing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutcomeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Plan created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "plan"
                  ],
                  "properties": {
                    "plan": {
                      "$ref": "#/components/schemas/OutcomePlan"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Preview temporarily unavailable"
          }
        }
      }
    },
    "/outcome/v1/check": {
      "post": {
        "tags": [
          "Outcome Receipt"
        ],
        "summary": "Check receipt structure and binding",
        "description": "Checks structure, digests and request binding. It does not authenticate the evidence producer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "request",
                  "receipt"
                ],
                "properties": {
                  "request": {
                    "$ref": "#/components/schemas/OutcomeRequest"
                  },
                  "receipt": {
                    "$ref": "#/components/schemas/OutcomeReceipt"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "verification"
                  ],
                  "properties": {
                    "verification": {
                      "$ref": "#/components/schemas/OutcomeVerification"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          }
        }
      }
    },
    "/api/basket/schema": {
      "get": {
        "tags": [
          "Basket Repair"
        ],
        "summary": "Read Basket Repair contract and JSON Schema",
        "responses": {
          "200": {
            "description": "Service contract",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/basket/example": {
      "get": {
        "tags": [
          "Basket Repair"
        ],
        "summary": "Read a synthetic Basket Repair example",
        "responses": {
          "200": {
            "description": "Synthetic example",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/basket/v1/basket/solve": {
      "post": {
        "tags": [
          "Basket Repair"
        ],
        "summary": "Solve one bounded basket",
        "description": "No billing, purchase, supplier request or live-price fetch.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "problem"
                ],
                "properties": {
                  "problem": {
                    "$ref": "#/components/schemas/BasketProblem"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bounded result envelope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "result"
                  ],
                  "properties": {
                    "result": {
                      "$ref": "#/components/schemas/BasketResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Unavailable"
          }
        }
      }
    },
    "/api/basket/v1/basket/verify": {
      "post": {
        "tags": [
          "Basket Repair"
        ],
        "summary": "Independently check a basket result",
        "description": "Verifies input binding, assignment, total, minimums, budget and supplier limit; does not independently rerun the optimization search.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "problem",
                  "receipt"
                ],
                "properties": {
                  "problem": {
                    "$ref": "#/components/schemas/BasketProblem"
                  },
                  "receipt": {
                    "type": "object",
                    "required": [
                      "input_sha256",
                      "supplier_for_item",
                      "total_cents"
                    ],
                    "properties": {
                      "input_sha256": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                      },
                      "supplier_for_item": {
                        "type": "array",
                        "items": {
                          "type": "integer",
                          "minimum": 0
                        }
                      },
                      "total_cents": {
                        "type": "integer",
                        "minimum": 0
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "verification"
                  ],
                  "properties": {
                    "verification": {
                      "type": "object",
                      "required": [
                        "valid",
                        "errors"
                      ],
                      "properties": {
                        "valid": {
                          "type": "boolean"
                        },
                        "errors": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OutcomeRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "operation_id",
          "intent",
          "target",
          "postconditions"
        ],
        "properties": {
          "schema": {
            "const": "foxify-outcome-request/v1"
          },
          "operation_id": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "intent": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "target": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "postconditions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "statement",
                "authority"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 64,
                  "pattern": "^[a-z][a-z0-9._-]*$"
                },
                "statement": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                },
                "authority": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "kind",
                    "locator"
                  ],
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "provider_readback",
                        "exact_owner",
                        "public_runtime"
                      ]
                    },
                    "locator": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 300
                    }
                  }
                }
              }
            }
          }
        }
      },
      "OutcomePlan": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "request_sha256",
          "operation_id",
          "checks",
          "retry_rule",
          "payment"
        ],
        "properties": {
          "schema": {
            "const": "foxify-outcome-plan/v1"
          },
          "request_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "operation_id": {
            "type": "string"
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "retry_rule": {
            "type": "string"
          },
          "payment": {
            "type": "object"
          }
        }
      },
      "OutcomeReceipt": {
        "type": "object",
        "required": [
          "schema",
          "operation_id",
          "request_sha256",
          "verdict",
          "observations",
          "retry_decision",
          "retry_safe",
          "boundary",
          "receipt_sha256"
        ],
        "properties": {
          "schema": {
            "const": "foxify-outcome-receipt/v1"
          },
          "operation_id": {
            "type": "string"
          },
          "request_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "verdict": {
            "type": "string",
            "enum": [
              "PROVED",
              "DISPROVED",
              "UNKNOWN"
            ]
          },
          "observations": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "retry_decision": {
            "type": "string",
            "enum": [
              "DO_NOT_REPEAT",
              "HOLD"
            ]
          },
          "retry_safe": {
            "const": false
          },
          "boundary": {
            "type": "string"
          },
          "receipt_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      },
      "OutcomeVerification": {
        "type": "object",
        "required": [
          "valid",
          "reasons"
        ],
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "request_sha256": {
            "type": "string"
          },
          "receipt_sha256": {
            "type": "string"
          }
        }
      },
      "BasketProblem": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "$id": "urn:foxify:basket-problem:v1",
        "title": "FOXIFY Basket Repair input",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "prices_cents",
          "shipping_cents",
          "minimum_order_cents",
          "max_suppliers",
          "budget_cents"
        ],
        "properties": {
          "schema": {
            "const": "basket-problem/v1"
          },
          "source": {
            "type": "string",
            "maxLength": 160
          },
          "prices_cents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "items": {
              "type": "array",
              "minItems": 1,
              "maxItems": 6,
              "items": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000000
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "description": "One row is one indivisible item/unit; columns are suppliers. null means unavailable, 0 is a real zero-price offer."
          },
          "shipping_cents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000000
            },
            "description": "Charged once per supplier used."
          },
          "minimum_order_cents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000000
            },
            "description": "Minimum merchandise subtotal for each used supplier, excluding shipping."
          },
          "max_suppliers": {
            "type": "integer",
            "minimum": 1,
            "maximum": 6
          },
          "budget_cents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000
          }
        },
        "$comment": "Runtime additionally requires equal supplier-vector/row lengths and max_suppliers <= actual supplier count. All prices share one caller-defined currency with two decimal places; no conversion is performed."
      },
      "BasketResult": {
        "type": "object",
        "required": [
          "schema",
          "input_sha256",
          "status",
          "feasible",
          "proof_complete"
        ],
        "properties": {
          "schema": {
            "const": "basket-result/v1"
          },
          "input_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "OPTIMAL",
              "INFEASIBLE",
              "FEASIBLE_LIMIT",
              "UNKNOWN"
            ]
          },
          "feasible": {
            "type": "boolean"
          },
          "proof_complete": {
            "type": "boolean"
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "supplier_for_item": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "total_cents": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "path": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "Request body exceeds the documented limit",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Use application/json",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "x-foxify-boundary": "This specification covers the live free REST core only. MCP and paid x402 preflight are separate adapters and do not gain execution authority from this document."
}
