{
  "openapi": "3.1.0",
  "info": {
    "title": "MyFlohmarkt Agent API",
    "version": "1.1.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": "Public flea market discovery endpoints for agents."
    },
    {
      "name": "Metadata",
      "description": "Minimal agent service health metadata."
    }
  ],
  "paths": {
    "/events/search": {
      "get": {
        "tags": ["Events"],
        "operationId": "searchAgentEvents",
        "summary": "Search public flea market events",
        "description": "Search the public event catalogue by text, city, date window, or coordinates. The response is intentionally reduced, read-only, bounded to 50 results, and rate-limited for agents.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Natural German search text. Alias: q."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Natural German search text alias."
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "City name or 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. Supply lat, lng, and radiusKm together."
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "format": "double"
            },
            "description": "Longitude for radius search. Supply lat, lng, and radiusKm together."
          },
          {
            "name": "radiusKm",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "description": "Radius in kilometres. Supply lat, lng, and radiusKm together."
          },
          {
            "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 an overlong search term, limit above 50, or an incomplete radius triplet."
          },
          "429": {
            "description": "The process-wide or per-client request rate limit is exhausted.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before retrying the request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "The process-wide, per-client, or bounded DuckDB query capacity is temporarily exhausted.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before retrying the request.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/ready": {
      "get": {
        "tags": ["Metadata"],
        "operationId": "getAgentReadiness",
        "summary": "Get agent service readiness",
        "description": "Returns 200 when the agent service is ready and 503 while it is starting.",
        "responses": {
          "200": {
            "description": "Successful JSON response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "503": {
            "description": "Agent service 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"
                }
              }
            }
          }
        }
      }
    }
  }
}