{
  "openapi": "3.1.0",
  "info": {
    "title": "Makore Events API",
    "version": "1.0.0",
    "description": "Public, read-only discovery of upcoming events in Israel. No authentication or API key required. Dates use Asia/Jerusalem. Search results are ordered by event start time. Developer quickstart, sandbox and MCP connection instructions: https://www.makore.co.il/developers."
  },
  "externalDocs": {
    "description": "Developer portal and quickstart",
    "url": "https://www.makore.co.il/developers"
  },
  "security": [],
  "servers": [{ "url": "https://api.makore.co.il" }],
  "paths": {
    "/v1/events": {
      "get": {
        "operationId": "searchEvents",
        "summary": "Search upcoming events",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": { "type": "string", "minLength": 3, "maxLength": 120 }
          },
          {
            "name": "district",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["ירושלים והסביבה", "צפון", "גוש דן", "דרום", "שרון"]
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Cannot be combined with district.",
            "schema": { "type": "string", "maxLength": 80 }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "הופעות חיות",
                "תיאטרון",
                "סטנדאפ",
                "תערוכה",
                "סדנה",
                "אירועי תוכן",
                "פעילות ספורטיבית",
                "ילדים ומשפחה",
                "סיור מודרך",
                "קולנוע",
                "קולינריה",
                "חיי לילה"
              ]
            }
          },
          {
            "name": "dateFrom",
            "in": "query",
            "description": "YYYY-MM-DD, defaults to today in Israel.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "dateTo",
            "in": "query",
            "description": "Inclusive YYYY-MM-DD, defaults to 30 days after dateFrom. Maximum 31 days per search, within the next 180 days.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque nextCursor from a prior response. Repeat the same filters.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Upcoming event page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["events", "nextCursor"],
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Event" }
                    },
                    "nextCursor": { "type": ["string", "null"] }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "operationId": "getEvent",
        "summary": "Look up an upcoming event by its stable ID",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Event",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Event" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": {
            "description": "Event does not exist or is no longer upcoming",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid search filters",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Too many requests. Wait before retrying.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": { "type": "integer", "minimum": 1 }
          }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "Database unavailable or at capacity",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "description": "Human-readable error and recovery guidance" }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "title",
          "startDate",
          "categories",
          "availabilityStatus",
          "updatedAt",
          "detailUrl"
        ],
        "properties": {
          "id": { "type": "string", "description": "Stable 64-character event hash" },
          "title": { "type": "string" },
          "description": { "type": ["string", "null"] },
          "startDate": { "type": "string", "format": "date-time" },
          "endDate": { "type": ["string", "null"], "format": "date-time" },
          "location": { "type": ["string", "null"] },
          "city": { "type": ["string", "null"] },
          "district": { "type": ["string", "null"] },
          "categories": { "type": "array", "items": { "type": "string" } },
          "cost": { "type": ["string", "null"] },
          "isFree": { "type": ["boolean", "null"] },
          "availabilityStatus": { "type": "string", "enum": ["unknown", "available", "sold_out"] },
          "updatedAt": { "type": "string", "format": "date-time" },
          "detailUrl": { "type": "string", "format": "uri" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" }
        }
      }
    }
  }
}