{
  "openapi": "3.1.0",
  "info": {
    "title": "Mamaput.ng Food & Delivery API",
    "description": "Mamaput menu, kitchen availability, delivery quoting and hosted Paystack checkout. Clients must explicitly connect to the API. Quotes disclose the actual configured courier or manual fallback. Custom ACP/UCP-shaped endpoints are experimental; protocol certification and automatic shopping discovery have not been established.",
    "termsOfService": "https://mamaput.ng/terms",
    "version": "1.1.0",
    "contact": {
      "name": "Mamaput.ng Kitchen Support",
      "email": "hello@mamaput.ng",
      "url": "https://mamaput.ng/support"
    }
  },
  "servers": [
    {
      "url": "https://mamaput.ng",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getKitchenStatus",
        "summary": "Check kitchen operational status and hours",
        "description": "Checks if the kitchen is currently open, active service modes (Belleful Hours, Chop As You Like, Frozen soup bowls, Party Packs), lead times, and operating rules in Lagos time.",
        "responses": {
          "200": {
            "description": "Kitchen status successfully returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "open": {
                      "type": "boolean"
                    },
                    "serviceOpen": {
                      "type": "boolean"
                    },
                    "belleful": {
                      "type": "boolean",
                      "description": "True if Belleful Hours (11am-4pm weekdays) is active now"
                    },
                    "today": {
                      "type": "string"
                    },
                    "workday": {
                      "type": "boolean"
                    },
                    "holiday": {
                      "type": "boolean"
                    },
                    "kitchen": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "address": {
                          "type": "string"
                        },
                        "whatsapp": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/menu": {
      "get": {
        "operationId": "getMenu",
        "summary": "Browse food menu and live dishes",
        "description": "Retrieves the full list of dishes (Belleful Hours, Chop As You Like, 1.8L and 2.5L frozen soup tubs, Party packs, bulk moin-moin, snacks, drinks), prices in Nigerian Naira (₦), and stock status.",
        "responses": {
          "200": {
            "description": "Menu items list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MenuItem"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/delivery/quote": {
      "post": {
        "operationId": "getDeliveryQuote",
        "summary": "Calculate delivery fee and ETA for Lagos address",
        "description": "Returns a delivery quote for a supported Lagos address. Reports the actual provider, including manual kitchen-rider fallback when configured couriers cannot quote.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "items"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "Full street address in Lagos including area/neighborhood (e.g. '14 Allen Avenue, Ikeja, Lagos')"
                  },
                  "customer": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string",
                        "description": "Nigerian phone number (e.g. '08031234567')"
                      }
                    }
                  },
                  "items": {
                    "type": "array",
                    "description": "List of dishes to deliver",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "qty"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Dish ID from getMenu (e.g. 'bh-jollof-beef')"
                        },
                        "qty": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "option": {
                          "type": "string",
                          "description": "Dish option choice (e.g. 'Egusi' or 'Egg')"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delivery quote calculated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "quoteId": {
                      "type": "string"
                    },
                    "fee": {
                      "type": "number",
                      "description": "Delivery fee in Naira (₦)"
                    },
                    "eta": {
                      "type": "string",
                      "description": "Estimated arrival time"
                    },
                    "partner": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "Place order and generate 1-click Paystack checkout link",
        "description": "Creates a delivery or pickup order and hosted Paystack checkout link. Validate availability, customer details and the complete total first. A link does not confirm payment or courier dispatch.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "customer",
                  "items"
                ],
                "properties": {
                  "fulfilment": {
                    "type": "string",
                    "enum": [
                      "delivery",
                      "pickup"
                    ],
                    "default": "delivery",
                    "description": "'delivery' for doorstep courier delivery, 'pickup' for Ikeja kitchen pickup"
                  },
                  "address": {
                    "type": "string",
                    "description": "Delivery street address in Lagos (required if fulfilment is 'delivery')"
                  },
                  "quoteId": {
                    "type": "string",
                    "description": "Optional pre-calculated quoteId from getDeliveryQuote"
                  },
                  "customer": {
                    "type": "object",
                    "required": [
                      "name",
                      "phone"
                    ],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string",
                        "description": "Nigerian phone number"
                      },
                      "email": {
                        "type": "string"
                      }
                    }
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "qty"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "qty": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "option": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created. Direct the user to paymentUrl to finalize purchase on Paystack.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "paymentUrl": {
                      "type": "string",
                      "description": "Paystack checkout URL"
                    },
                    "total": {
                      "type": "number",
                      "description": "Total charged in Naira (₦)"
                    },
                    "deliveryFee": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/acp/sessions": {
      "post": {
        "operationId": "createAgenticCheckoutSession",
        "summary": "Agentic Commerce Protocol (ACP) Instant Checkout Session",
        "description": "Experimental custom checkout session with server pricing, packaging, actual delivery provider and hosted Paystack handoff. ACP conformance has not been verified.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "customer",
                  "items"
                ],
                "properties": {
                  "fulfilment": {
                    "type": "string",
                    "enum": [
                      "delivery",
                      "pickup"
                    ],
                    "default": "delivery"
                  },
                  "deliveryAddress": {
                    "type": "string",
                    "description": "Lagos street address"
                  },
                  "customer": {
                    "type": "object",
                    "required": [
                      "name",
                      "phone"
                    ],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string"
                      }
                    }
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "qty"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "qty": {
                          "type": "integer"
                        },
                        "option": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "ACP checkout session created with payment action.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "protocol": {
                      "type": "string",
                      "example": "ACP/1.0"
                    },
                    "session_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "example": "requires_payment"
                    },
                    "pricing": {
                      "type": "object",
                      "properties": {
                        "subtotal": {
                          "type": "number"
                        },
                        "delivery_fee": {
                          "type": "number"
                        },
                        "total": {
                          "type": "number"
                        }
                      }
                    },
                    "checkout_action": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "example": "redirect_url"
                        },
                        "url": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/acp/sessions/{id}": {
      "get": {
        "operationId": "getAgenticCheckoutSession",
        "summary": "Check ACP session status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session details and payment completion state."
          }
        }
      }
    },
    "/api/acp/products": {
      "get": {
        "operationId": "getAgenticProductCatalog",
        "summary": "Retrieve experimental ACP-shaped product catalogue",
        "description": "Returns standard product objects with pricing, options, and stock state for AI agent catalog search.",
        "responses": {
          "200": {
            "description": "Product catalogue in ACP format."
          }
        }
      }
    },
    "/api/ucp/catalog": {
      "get": {
        "operationId": "getUcpCatalog",
        "summary": "Universal Commerce Protocol (UCP) Catalog",
        "description": "Returns standard UCP catalog feed (dev.ucp.shopping.catalog) for Google AI and Gemini shopping agents.",
        "responses": {
          "200": {
            "description": "UCP catalog successfully returned."
          }
        }
      }
    },
    "/api/ucp/cart": {
      "post": {
        "operationId": "createOrUpdateUcpCart",
        "summary": "Universal Commerce Protocol (UCP) Cart Creation",
        "description": "Experimental custom cart with server pricing and delivery provider reporting. UCP conformance and platform enrollment have not been verified.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array"
                  },
                  "fulfillment": {
                    "type": "object"
                  },
                  "customer": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "UCP cart updated."
          }
        }
      }
    },
    "/api/ucp/checkout": {
      "post": {
        "operationId": "processUcpCheckout",
        "summary": "Universal Commerce Protocol (UCP) Checkout Execution",
        "description": "Executes checkout session (dev.ucp.shopping.checkout) and returns Paystack redirect payment handoff.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cart_id": {
                    "type": "string"
                  },
                  "customer": {
                    "type": "object"
                  },
                  "address": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout initiated with payment handoff."
          }
        }
      }
    },
    "/api/ucp/orders/{id}": {
      "get": {
        "operationId": "getUcpOrderStatus",
        "summary": "Universal Commerce Protocol (UCP) Order Status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "UCP order status details."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MenuItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "section": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "Price in Naira (₦)"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "soldOut": {
            "type": "boolean"
          }
        }
      }
    }
  }
}