{
  "openapi": "3.1.0",
  "info": {
    "title": "Utopia Megastore Agent Commerce API",
    "version": "1.2.0",
    "description": "Machine-purchasable catalog, negotiation, set-building and checkout for AI shopping agents. Currency USD. Free shipping over $60. Negotiation floor: supplier cost + 12% margin. Payment capture auto-forwards the order to CJ Dropshipping with USPS last-mile.",
    "contact": {
      "email": "timlangeveldt@gmail.com",
      "url": "https://utopia-megastore.pages.dev/"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://utopia-orders.precogsecurity.workers.dev",
      "description": "Utopia orders worker"
    }
  ],
  "tags": [
    {
      "name": "catalog"
    },
    {
      "name": "pricing"
    },
    {
      "name": "orders"
    },
    {
      "name": "agents"
    },
    {
      "name": "social"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "tags": [
          "catalog"
        ],
        "operationId": "listProducts",
        "summary": "Full catalog: products, bundles, payment methods, API map",
        "responses": {
          "200": {
            "description": "Catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "post": {
        "tags": [
          "catalog"
        ],
        "operationId": "searchProducts",
        "summary": "Fuzzy product search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string"
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked matches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "matches": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    "bundles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bundle"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bundle/suggest": {
      "post": {
        "tags": [
          "pricing"
        ],
        "operationId": "suggestBundle",
        "summary": "Build a set within a budget using cross-subsidized pricing",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "budget": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bundles plus custom cross-subsidized combinations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "proposed_items": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "budget": {
                      "type": "number"
                    },
                    "bundles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bundle"
                      }
                    },
                    "custom_cross_subsidy": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CrossSubsidy"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/negotiate": {
      "post": {
        "tags": [
          "pricing"
        ],
        "operationId": "negotiate",
        "summary": "Propose a target price; server answers with the best legal price",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "budget": {
                    "type": "number"
                  },
                  "caller": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Best price at or above the floor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "retail_total": {
                      "type": "number"
                    },
                    "proposed_price": {
                      "type": "number"
                    },
                    "discount": {
                      "type": "number"
                    },
                    "applied_bundle": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "pay_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/split-payments": {
      "post": {
        "tags": [
          "pricing"
        ],
        "operationId": "validateSplit",
        "summary": "Validate that a multi-recipient allocation sums to the order total",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "price": {
                          "type": "number"
                        },
                        "qty": {
                          "type": "integer"
                        }
                      }
                    }
                  },
                  "split": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/SplitShare"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Allocation check",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "allocOk": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "number"
                    },
                    "splitTotal": {
                      "type": "number"
                    },
                    "discrepancy": {
                      "type": "number"
                    },
                    "recipients": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SplitShare"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "tags": [
          "orders"
        ],
        "operationId": "checkout",
        "summary": "Create an order and return a PayPal payment URL",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "caller": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "price": {
                          "type": "number"
                        },
                        "qty": {
                          "type": "integer"
                        },
                        "cj_vid": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "total": {
                    "type": "number"
                  },
                  "split": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/SplitShare"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created, awaiting payment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "number"
                    },
                    "pay_url": {
                      "type": "string"
                    },
                    "instruction": {
                      "type": "string"
                    },
                    "supplier_status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/order": {
      "post": {
        "tags": [
          "orders"
        ],
        "operationId": "createOrder",
        "summary": "Create and finalize an order (triggers CJ supplier forwarding)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "total": {
                    "type": "number"
                  },
                  "payment_method": {
                    "type": "string"
                  },
                  "shipping_address": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "paypal_order": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "email",
                  "items",
                  "total"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order persisted; supplier field reports forwarding state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "orderId": {
                      "type": "integer"
                    },
                    "supplier": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/register": {
      "post": {
        "tags": [
          "agents"
        ],
        "operationId": "registerAgent",
        "summary": "Register an AI agent and receive an agent_key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "owner": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent key issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "agent_key": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    },
                    "catalog_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "tags": [
          "agents"
        ],
        "operationId": "listAgents",
        "summary": "List the most recently registered agents",
        "responses": {
          "200": {
            "description": "Agent list (no keys exposed)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "owner": {
                            "type": "string"
                          },
                          "registered_at": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/reviews": {
      "get": {
        "tags": [
          "social"
        ],
        "operationId": "listReviews",
        "summary": "Reviews and per-product rating aggregates",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews plus stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "stats": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "orders"
        ],
        "operationId": "getStats",
        "summary": "Aggregate store statistics",
        "responses": {
          "200": {
            "description": "Aggregates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orders": {
                      "type": "integer"
                    },
                    "revenue": {
                      "type": "number"
                    },
                    "members": {
                      "type": "integer"
                    },
                    "users": {
                      "type": "integer"
                    },
                    "vendors": {
                      "type": "integer"
                    },
                    "forwarded": {
                      "type": "integer"
                    },
                    "commissions": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "AgentKey": {
        "name": "X-Agent-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "agent_key from /api/agent/register; enables negotiation history and repeat-order pricing"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "bulk": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "image": {
            "type": "string"
          },
          "desc": {
            "type": "string"
          },
          "cj_vid": {
            "type": "string"
          }
        }
      },
      "Bundle": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image": {
            "type": "string"
          }
        }
      },
      "CrossSubsidy": {
        "type": "object",
        "properties": {
          "big": {
            "type": "string"
          },
          "cheap1": {
            "type": "string"
          },
          "cheap2": {
            "type": "string"
          },
          "retail": {
            "type": "number"
          },
          "bundle": {
            "type": "number"
          },
          "savings": {
            "type": "number"
          },
          "allocation": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            }
          }
        }
      },
      "SplitShare": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          }
        }
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "store": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "free_shipping_over": {
            "type": "number"
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "bundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Bundle"
            }
          },
          "agent_friendly": {
            "type": "boolean"
          },
          "api": {
            "type": "object"
          }
        }
      }
    }
  }
}