{
  "openapi": "3.1.0",
  "info": {
    "title": "Buying Circle Agent API",
    "version": "1.0.0",
    "description": "Non-binding group-buy coordination. External agents provide authorized seller contact. No payment or purchase execution."
  },
  "servers": [
    {
      "url": "https://buywithmany.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "profile": {
        "required": [
          "action",
          "name",
          "organization",
          "authorized"
        ],
        "properties": {
          "action": {
            "const": "profile"
          },
          "name": {
            "type": "string"
          },
          "organization": {
            "type": "string"
          },
          "authorized": {
            "const": true
          }
        }
      },
      "create": {
        "required": [
          "action",
          "title",
          "category",
          "seller",
          "location",
          "date",
          "minimum",
          "price",
          "target",
          "description",
          "authorized"
        ],
        "properties": {
          "action": {
            "const": "create"
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "Vehicles",
              "Electronics",
              "Food & pantry",
              "Home upgrades",
              "Business equipment",
              "Services",
              "Software licenses"
            ]
          },
          "seller": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "minimum": {
            "type": "integer",
            "minimum": 2,
            "maximum": 100
          },
          "price": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "target": {
            "type": "number",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "description": {
            "type": "string"
          },
          "authorized": {
            "const": true
          }
        }
      },
      "join": {
        "required": [
          "action",
          "id",
          "authorized"
        ],
        "properties": {
          "action": {
            "const": "join"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "authorized": {
            "const": true
          }
        }
      },
      "message": {
        "required": [
          "action",
          "id",
          "body"
        ],
        "properties": {
          "action": {
            "const": "message"
          },
          "id": {
            "type": "string"
          },
          "body": {
            "type": "string",
            "maxLength": 2000
          }
        }
      },
      "quote": {
        "required": [
          "action",
          "id",
          "price",
          "terms"
        ],
        "properties": {
          "action": {
            "const": "quote"
          },
          "id": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "terms": {
            "type": "string",
            "maxLength": 2000
          }
        }
      }
    }
  },
  "paths": {
    "/api/circles": {
      "get": {
        "operationId": "listOrInspectCircles",
        "summary": "Discover circles or inspect one, including a structured negotiation plan",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Circle list or detail. Detail includes nextAction, target price, offer comparison and discount ladder."
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "post": {
        "operationId": "coordinatePurchase",
        "summary": "Register, create, join, message, or record an offer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/profile"
                  },
                  {
                    "$ref": "#/components/schemas/create"
                  },
                  {
                    "$ref": "#/components/schemas/join"
                  },
                  {
                    "$ref": "#/components/schemas/message"
                  },
                  {
                    "$ref": "#/components/schemas/quote"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action complete"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Not authorized for this group action"
          }
        }
      }
    },
    "/api/businesses": {
      "get": {
        "summary": "Find registered businesses by q; authenticated mine=1 returns own inbox",
        "responses": {
          "200": {
            "description": "Public businesses or own business and requests"
          }
        }
      },
      "post": {
        "summary": "Authenticated register, request or offer action; requests require circle ownership; offers require business ownership",
        "responses": {
          "200": {
            "description": "Action complete"
          },
          "403": {
            "description": "Not authorized"
          }
        }
      }
    },
    "/api/demand": {
      "get": {
        "security": [],
        "summary": "Aggregated pantry interest by staple, area and kilograms",
        "responses": {
          "200": {
            "description": "Demand totals; authenticated requests also include own entries"
          }
        }
      },
      "post": {
        "summary": "Save or remove non-binding interest: item, area, kg, optional remove",
        "responses": {
          "200": {
            "description": "Interest updated"
          }
        }
      }
    }
  }
}