{
  "openapi": "3.1.0",
  "info": {
    "title": "LIVO public catalog (read-only)",
    "version": "1.1.0",
    "summary": "Read-only discovery of LIVO's public modules, businesses, events, shop products and TREK route previews.",
    "description": "LIVO (livoapp.live) is a Hebrew-first life OS: community, music, fitness, local businesses, events and a shop. This API exposes ONLY what is already public on the website. It is read-only: no authentication, no personal data, no user-generated private content, no payments and no writes. To act (book, buy, message), send the user to the returned `url` — every action happens on LIVO by the signed-in user. Rate limit: 60 requests per minute per IP (HTTP 429 with Retry-After).",
    "contact": {
      "url": "https://livoapp.live/contact"
    }
  },
  "servers": [
    {
      "url": "https://livoapp.live"
    }
  ],
  "externalDocs": {
    "description": "Plain-text guide for language models",
    "url": "https://livoapp.live/llms.txt"
  },
  "x-livo-deep-links": [
    {
      "pattern": "https://livoapp.live/biz",
      "description": "Business directory (Hebrew UI)."
    },
    {
      "pattern": "https://livoapp.live/biz/c/{categoryKey}",
      "description": "Businesses in one category, e.g. /biz/c/garage."
    },
    {
      "pattern": "https://livoapp.live/biz/{slug}",
      "description": "A business page (canonical). Use the `url` returned by the catalog; businesses without a slug live at /biz/p/{id}."
    },
    {
      "pattern": "https://livoapp.live/events",
      "description": "Upcoming public events."
    },
    {
      "pattern": "https://livoapp.live/events/{id}",
      "description": "One public event."
    },
    {
      "pattern": "https://livoapp.live/shop?q={text}&city={city}&kind={new|used|rent}&sort={newest|price_asc|price_desc}",
      "description": "Shop search with pre-filled filters."
    },
    {
      "pattern": "https://livoapp.live/shop/category/{categoryId}",
      "description": "Shop category page."
    },
    {
      "pattern": "https://livoapp.live/shop/product/{id}",
      "description": "One product page. Purchase always happens on LIVO by the signed-in user, never through this API."
    },
    {
      "pattern": "https://livoapp.live/{moduleKey}",
      "description": "Module entry points — use the `url` field from /api/public/catalog/modules."
    }
  ],
  "paths": {
    "/api/public/catalog/trek-routes": {
      "get": {
        "operationId": "listTrekRoutePreviews",
        "summary": "Curated route summaries already shown in the guest gateway.",
        "description": "Catalog previews only, with no user trips, geometry or live conditions. The URL opens TREK; it is not a current route recommendation.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Free-text search (Hebrew or English)."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public, read-only list.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "resource",
                    "count",
                    "items",
                    "readOnly"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "resource": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "readOnly": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TrekRoutePreview"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadQuery"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/public/catalog/modules": {
      "get": {
        "operationId": "listModules",
        "summary": "LIVO modules and their entry URLs.",
        "responses": {
          "200": {
            "description": "Public, read-only list.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "resource",
                    "count",
                    "items",
                    "readOnly"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "resource": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "readOnly": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Module"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadQuery"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/public/catalog/businesses": {
      "get": {
        "operationId": "listBusinesses",
        "summary": "Active local businesses with a public page on LIVO.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Free-text search (Hebrew or English)."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public, read-only list.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "resource",
                    "count",
                    "items",
                    "readOnly"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "resource": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "readOnly": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Business"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadQuery"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/public/catalog/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "Upcoming approved public events.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Free-text search (Hebrew or English)."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public, read-only list.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "resource",
                    "count",
                    "items",
                    "readOnly"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "resource": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "readOnly": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadQuery"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/public/catalog/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "Active shop products (demo items excluded).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            },
            "description": "Free-text search (Hebrew or English)."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "used",
                "rent"
              ]
            }
          },
          {
            "name": "minPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "maxPrice",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public, read-only list.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "resource",
                    "count",
                    "items",
                    "readOnly"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "resource": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "readOnly": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadQuery"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadQuery": {
        "description": "Invalid query parameter.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "Temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string"
          },
          "field": {
            "type": "string"
          }
        }
      },
      "Module": {
        "type": "object",
        "required": [
          "key",
          "name",
          "url",
          "indexable"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "space": {
            "type": [
              "string",
              "null"
            ]
          },
          "indexable": {
            "type": "boolean",
            "description": "false = personal surface; the user signs in on arrival."
          }
        }
      },
      "Business": {
        "type": "object",
        "required": [
          "id",
          "name",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "website": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "rating": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "average": {
                "type": "number",
                "minimum": 0,
                "maximum": 5
              },
              "count": {
                "type": "integer"
              }
            }
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "price": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "currency": {
                  "const": "ILS"
                },
                "durationMinutes": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "title",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": "string"
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "startDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "ticketUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "price": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "const": "ILS"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "title",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "condition": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "new",
              "used",
              "rent",
              null
            ]
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "isDigital": {
            "type": "boolean"
          },
          "inStock": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "TrekRoutePreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "region",
          "distanceKm",
          "estimatedHours",
          "difficulty",
          "url",
          "preview"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "distanceKm": {
            "type": "number"
          },
          "estimatedHours": {
            "type": "number"
          },
          "difficulty": {
            "enum": [
              "easy",
              "medium",
              "hard",
              "extreme"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "preview": {
            "const": true
          }
        }
      }
    }
  }
}