{
  "openapi": "3.1.0",
  "info": {
    "title": "MyFlohmarkt Agent API",
    "version": "1.0.0",
    "description": "Read-only agent discovery API for current German flea market dates. MCP-capable clients should prefer https://mcp.my-flohmarkt.de/mcp; this OpenAPI document describes the REST fallback on the same public agent host. Use it for lightweight live lookups, not bulk export."
  },
  "servers": [
    {
      "url": "https://mcp.my-flohmarkt.de",
      "description": "Production agent API"
    }
  ],
  "externalDocs": {
    "description": "Model Context Protocol endpoint for MCP-capable agents.",
    "url": "https://mcp.my-flohmarkt.de/mcp"
  },
  "tags": [
    {
      "name": "Events",
      "description": "Cached public flea market discovery endpoints for agents."
    },
    {
      "name": "Metadata",
      "description": "Agent service and cache metadata."
    }
  ],
  "paths": {
    "/events/search": {
      "get": {
        "tags": ["Events"],
        "operationId": "searchAgentEvents",
        "summary": "Search cached public flea market events",
        "description": "Search the cached public event catalogue by text, city, date window, or coordinates. The response is intentionally reduced, read-only, cache-backed, and rate-limited for agents.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Natural German search text. Alias: q."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Natural German search text alias."
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "City name or exact German postal code text."
          },
          {
            "name": "dateFrom",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Start date, inclusive."
          },
          {
            "name": "dateTo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "End date, inclusive."
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "format": "double"
            },
            "description": "Latitude for radius search."
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "format": "double"
            },
            "description": "Longitude for radius search."
          },
          {
            "name": "radiusKm",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "description": "Radius in kilometres for coordinate or city-centre search."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "Maximum result count. Larger values are rejected with 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful JSON response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query shape, for example limit above 50."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/cache/status": {
      "get": {
        "tags": ["Metadata"],
        "operationId": "getAgentCacheStatus",
        "summary": "Get agent catalogue cache status",
        "description": "Returns cache readiness, current cached event count, refresh timestamps, refresh interval, maximum cached event count, and the last refresh error if any.",
        "responses": {
          "200": {
            "description": "Successful JSON response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": ["Metadata"],
        "operationId": "getAgentReadiness",
        "summary": "Get agent service readiness",
        "description": "Returns 200 when the agent catalogue cache is ready and 503 while the cache has not successfully refreshed yet.",
        "responses": {
          "200": {
            "description": "Successful JSON response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Agent cache is not ready yet."
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["Metadata"],
        "operationId": "getAgentHealth",
        "summary": "Get basic agent service health",
        "responses": {
          "200": {
            "description": "Successful JSON response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}