{
  "openapi": "3.1.0",
  "info": {
    "title": "CatalogHub Agent API",
    "version": "0.1.0-draft",
    "description": "Draft REST API for agent-ready hospitality catalogue discovery, baskets, orders, invoices, and deliveries."
  },
  "servers": [
    {
      "url": "https://api.cataloghub.example",
      "description": "Draft production API hostname"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/catalog/search": {
      "get": {
        "summary": "Search products",
        "description": "Search authorised supplier catalogues by product query and structured fields.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Search query, for example olive oil."
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Comma-separated fields such as allergens,nutrition,availability."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching catalogue products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CatalogProduct" }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/v1/suppliers": {
      "get": {
        "summary": "Discover suppliers",
        "responses": {
          "200": {
            "description": "Suppliers visible to the authenticated workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Supplier" }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/v1/baskets": {
      "post": {
        "summary": "Create basket",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateBasketRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Draft basket.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Basket" }
              }
            }
          }
        }
      }
    },
    "/v1/orders": {
      "post": {
        "summary": "Submit order",
        "responses": {
          "202": {
            "description": "Order accepted for processing."
          }
        }
      }
    },
    "/v1/invoices": {
      "get": {
        "summary": "Query invoices",
        "responses": {
          "200": {
            "description": "Invoice records for the authenticated workspace."
          }
        }
      }
    },
    "/v1/deliveries": {
      "get": {
        "summary": "Query deliveries",
        "responses": {
          "200": {
            "description": "Delivery records for the authenticated workspace."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "CatalogProduct": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "supplier": { "$ref": "#/components/schemas/Supplier" },
          "pack": { "type": "string" },
          "availability": { "type": "string", "enum": ["in_stock", "limited", "out_of_stock", "unknown"] },
          "allergens": { "type": "array", "items": { "type": "string" } },
          "nutrition": { "type": "object", "additionalProperties": true }
        },
        "required": ["id", "name", "supplier"]
      },
      "Supplier": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        },
        "required": ["id", "name"]
      },
      "CreateBasketRequest": {
        "type": "object",
        "properties": {
          "restaurant_id": { "type": "string" },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_id": { "type": "string" },
                "quantity": { "type": "number", "minimum": 0 }
              },
              "required": ["product_id", "quantity"]
            }
          }
        },
        "required": ["restaurant_id", "items"]
      },
      "Basket": {
        "type": "object",
        "properties": {
          "basket_id": { "type": "string" },
          "status": { "type": "string" },
          "currency": { "type": "string" },
          "totals": { "type": "object", "additionalProperties": true }
        },
        "required": ["basket_id", "status"]
      }
    }
  },
  "x-cataloghub-status": "draft"
}