{
  "openapi": "3.1.0",
  "info": {
    "title": "Limvero Public API",
    "version": "2026-06-14",
    "description": "Machine-readable reference for implemented Limvero public API endpoints only. This document does not expose a production try-it console."
  },
  "servers": [
    {
      "url": "https://api.limvero.com/api/v1",
      "description": "Production API origin."
    }
  ],
  "tags": [
    {
      "name": "Menu",
      "description": "Tenant-scoped menu reads."
    },
    {
      "name": "Orders",
      "description": "Tenant-scoped order reads."
    }
  ],
  "paths": {
    "/public/menu/items": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "List menu items",
        "description": "Reads tenant-scoped menu items using bounded cursor pagination.",
        "operationId": "listPublicMenuItems",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "limveroApiKey": []
          }
        ],
        "x-required-scopes": [
          "public.read",
          "menu.read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": "Maximum number of records to return. Backend accepts 1-100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Cursor from pagination.nextPageToken."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive search by menu item name or SKU."
          },
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by menu category inside the API key tenant."
          },
          {
            "name": "locationId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter prices/items by tenant location. POS-scoped sessions remain location bounded."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "STOP_LIST",
                "ARCHIVED"
              ]
            },
            "description": "Menu item status filter."
          }
        ],
        "responses": {
          "200": {
            "description": "Menu item page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MenuItem"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Validation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key is valid but does not include every required scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist inside the API key tenant boundary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Back off before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/public/orders": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "List orders",
        "description": "Reads tenant-scoped order lists using bounded filters and cursor pagination.",
        "operationId": "listPublicOrders",
        "security": [
          {
            "bearerApiKey": []
          },
          {
            "limveroApiKey": []
          }
        ],
        "x-required-scopes": [
          "public.read",
          "orders.read"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": "Maximum number of records to return. Backend accepts 1-100."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Cursor from pagination.nextPageToken."
          },
          {
            "name": "locationId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by tenant location."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "OPEN",
                "SENT_TO_KITCHEN",
                "PAID",
                "CLOSED",
                "CANCELLED"
              ]
            },
            "description": "Order status filter."
          },
          {
            "name": "activeOnly",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "When true, returns open and sent-to-kitchen orders."
          }
        ],
        "responses": {
          "200": {
            "description": "Order page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Validation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, revoked or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key is valid but does not include every required scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource does not exist inside the API key tenant boundary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Back off before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use Authorization: Bearer lv_live_REPLACE_WITH_YOUR_API_KEY."
      },
      "limveroApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Limvero-Api-Key",
        "description": "Alternative API key header using the same scoped key."
      }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "required": [
          "nextPageToken",
          "hasMore"
        ],
        "properties": {
          "nextPageToken": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass this value as cursor on the next request when hasMore is true."
          },
          "hasMore": {
            "type": "boolean",
            "description": "True when another page is available."
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string"
            }
          },
          "statusCode": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "MenuItem": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "STOP_LIST",
              "ARCHIVED"
            ]
          }
        },
        "additionalProperties": true
      },
      "Order": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "number": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "OPEN",
              "SENT_TO_KITCHEN",
              "PAID",
              "CLOSED",
              "CANCELLED"
            ]
          },
          "locationId": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": true
      }
    }
  }
}