{
  "openapi": "3.1.0",
  "info": {
    "title": "Flood Watch API",
    "version": "1.0.0",
    "summary": "Report flooding and query community flood reports in Thailand.",
    "description": "Public API behind https://flood.rooptanjai.com (ROOP TAN JAI). Two things an agent can do:\n\n1. **Report a flood**: `POST /api/reports` with a photo, the location and the water depth.\n2. **Query reports**: `GET /api/reports` for a map area (`bbox`) and time window (`since`).\n\nNo account or API key is needed. Rules:\n\n- **Rate limit:** 5 new reports per 10 minutes per client IP. More returns `429` (`rate_limited`). Queries are not rate limited.\n- **Reports are public:** everything except the private `delete_token` is visible to everyone on the map.\n- **Photos:** every report needs one photo (a base64 image data URL). `photo_url` / `thumb_url` in responses are short-lived signed URLs (about 1 hour), so fetch them promptly or query again for fresh ones.\n- **Delete:** a successful report returns a one-time `delete_token`. Keep it if you may need to remove the report; it can't be recovered.\n- **Server-side use:** browser CORS is limited to the Flood Watch site, so call the API from your server or agent runtime.",
    "contact": { "name": "ROOP TAN JAI", "url": "https://flood.rooptanjai.com/developers" }
  },
  "servers": [{ "url": "https://flood-api.rooptanjai.com", "description": "Production" }],
  "tags": [
    { "name": "Report", "description": "1 · Report a flood" },
    { "name": "Query", "description": "2 · Query reports" }
  ],
  "paths": {
    "/api/reports": {
      "post": {
        "operationId": "createReport",
        "tags": ["Report"],
        "summary": "Report a flood",
        "description": "Submit a flood report: a photo, where it was taken and how deep the water is. The report appears on the public map immediately. Rate limited to 5 per 10 minutes per client IP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateReport" },
              "examples": {
                "kneeDeep": {
                  "summary": "Knee-deep water on a street",
                  "value": {
                    "lat": 13.7563,
                    "lng": 100.5018,
                    "accuracy_m": 15,
                    "depth": "knee",
                    "note": "Road flooded, cars turning back",
                    "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report created. Keep `delete_token` if you may need to remove it later.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedReport" } } }
          },
          "400": {
            "description": "Invalid JSON (`invalid_json`, also for unknown fields) or invalid fields (`validation`, with a message per field).",
            "content": {
              "application/json": {
                "schema": { "oneOf": [{ "$ref": "#/components/schemas/ValidationError" }, { "$ref": "#/components/schemas/Error" }] },
                "examples": {
                  "validation": { "value": { "error": "validation", "fields": { "depth": "must be one of none, ankle, knee, waist" } } },
                  "invalidJson": { "value": { "error": "invalid_json" } }
                }
              }
            }
          },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      },
      "get": {
        "operationId": "listReports",
        "tags": ["Query"],
        "summary": "Query reports",
        "description": "List recent reports, newest first, optionally limited to a map area. Returns at most `limit` reports.",
        "parameters": [
          {
            "name": "bbox",
            "in": "query",
            "description": "Map area as `minLng,minLat,maxLng,maxLat` (WGS84 degrees). Omit for all areas.",
            "schema": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$" },
            "example": "100.45,13.70,100.60,13.80"
          },
          {
            "name": "since",
            "in": "query",
            "description": "Only reports newer than this: a Go duration (`24h`, `90m`, `168h`) or an RFC 3339 time. Default `24h`. Capped at 30 days (`720h`).",
            "schema": { "type": "string", "default": "24h" },
            "example": "168h"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of reports. Default 200. Values above 500 are capped at 500.",
            "schema": { "type": "integer", "minimum": 1, "default": 200 },
            "example": 100
          }
        ],
        "responses": {
          "200": {
            "description": "Matching reports, newest first.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportList" } } }
          },
          "400": {
            "description": "Invalid query parameter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValidationError" },
                "example": { "error": "validation", "fields": { "bbox": "must be minLng,minLat,maxLng,maxLat" } }
              }
            }
          },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/reports/{id}": {
      "delete": {
        "operationId": "deleteReport",
        "tags": ["Report"],
        "summary": "Remove your report",
        "description": "Remove a report you created, using the `delete_token` returned when it was created.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } },
          { "name": "X-Delete-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The `delete_token` from the create response." }
        ],
        "responses": {
          "204": { "description": "Removed." },
          "403": { "description": "Missing or wrong delete token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "No such report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Depth": {
        "type": "string",
        "enum": ["none", "ankle", "knee", "waist"],
        "description": "Water depth: `none` = no water (0 cm) · `ankle` = up to 20 cm · `knee` = 20–50 cm · `waist` = 50 cm or deeper."
      },
      "CreateReport": {
        "type": "object",
        "additionalProperties": false,
        "required": ["lat", "lng", "depth", "photo"],
        "properties": {
          "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude where the photo was taken (WGS84)." },
          "lng": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude where the photo was taken (WGS84)." },
          "accuracy_m": { "type": ["integer", "null"], "minimum": 0, "maximum": 100000, "description": "Location accuracy in metres, if known." },
          "depth": { "$ref": "#/components/schemas/Depth" },
          "note": { "type": "string", "maxLength": 500, "description": "Optional short note (up to 500 characters). Leading/trailing spaces are trimmed." },
          "photo": {
            "type": "string",
            "pattern": "^data:image/[a-z0-9.+-]+;base64,",
            "description": "The photo as a base64 data URL (`data:image/jpeg;base64,…`). JPEG, PNG or WebP, up to 1.5 MB decoded; the type is checked from the bytes. The server stores a full-size (≤1600 px) and a thumbnail (≤256 px) JPEG. Whole request body ≤ 2.2 MB."
          }
        }
      },
      "Report": {
        "type": "object",
        "required": ["id", "lat", "lng", "accuracy_m", "depth", "note", "photo_url", "thumb_url", "created_at"],
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "lat": { "type": "number" },
          "lng": { "type": "number" },
          "accuracy_m": { "type": ["integer", "null"] },
          "depth": { "$ref": "#/components/schemas/Depth" },
          "note": { "type": "string" },
          "photo_url": { "type": "string", "description": "Full-size photo. Usually a short-lived signed URL (about 1 hour)." },
          "thumb_url": { "type": "string", "description": "Thumbnail. Usually a short-lived signed URL (about 1 hour)." },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "CreatedReport": {
        "allOf": [
          { "$ref": "#/components/schemas/Report" },
          {
            "type": "object",
            "required": ["delete_token"],
            "properties": { "delete_token": { "type": "string", "description": "One-time secret for `DELETE /api/reports/{id}`. Returned only here; keep it private." } }
          }
        ]
      },
      "ReportList": {
        "type": "object",
        "required": ["reports"],
        "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } } }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "enum": ["invalid_json", "too_large", "rate_limited", "database_unavailable", "not_found", "forbidden", "internal", "method_not_allowed"]
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": ["error", "fields"],
        "properties": {
          "error": { "const": "validation" },
          "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field name → what is wrong with it." }
        }
      }
    },
    "responses": {
      "TooLarge": {
        "description": "Request body over 2.2 MB.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "too_large" } } }
      },
      "RateLimited": {
        "description": "More than 5 reports in 10 minutes from this client IP. Wait and retry.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited" } } }
      },
      "Unavailable": {
        "description": "The database is temporarily unavailable. Retry later.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "database_unavailable" } } }
      }
    }
  }
}
