{
  "openapi": "3.1.0",
  "info": {
    "title": "DamWatch USA API",
    "version": "1.0.0",
    "description": "Public, read-only access to curated educational dam records, bounded live USACE National Inventory of Dams queries, national counts, data-source discovery, health, and a JSON-RPC MCP transport. Created by Michael Barbine and published by PlatPhorm News.",
    "contact": {
      "name": "Michael Barbine",
      "url": "https://dam.platphormnews.com/about"
    },
    "license": {
      "name": "DamWatch USA license and source-data attribution policy",
      "url": "https://dam.platphormnews.com/license"
    }
  },
  "servers": [
    {
      "url": "https://dam.platphormnews.com"
    }
  ],
  "tags": [
    {
      "name": "Dam data",
      "description": "Curated educational records and live NID queries."
    },
    {
      "name": "Sources",
      "description": "Public source and learning-resource discovery."
    },
    {
      "name": "Platform",
      "description": "PlatPhormNews health, docs, and MCP surfaces."
    }
  ],
  "paths": {
    "/api/dams": {
      "get": {
        "tags": [
          "Dam data"
        ],
        "summary": "Search curated or live NID dam records",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "featured",
                "nid"
              ],
              "default": "featured"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "description": "NID source only."
          },
          {
            "name": "hazard",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "H",
                "S",
                "L",
                "U"
              ]
            },
            "description": "NID source only."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dam search result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "503": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    },
    "/api/dams/{id}": {
      "get": {
        "tags": [
          "Dam data"
        ],
        "summary": "Get one curated dam record",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Curated dam record"
          },
          "404": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "Dam data"
        ],
        "summary": "Get live NID inventory and hazard counts",
        "responses": {
          "200": {
            "description": "Live counts"
          },
          "503": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    },
    "/api/sources": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List public official, research, and community dam-data sources",
        "responses": {
          "200": {
            "description": "Source catalog"
          }
        }
      }
    },
    "/api/integrations": {
      "get": {
        "tags": [
          "Sources"
        ],
        "summary": "List integrated and linked public dam feeds, APIs, and tools",
        "responses": {
          "200": {
            "description": "Integration catalog"
          }
        }
      }
    },
    "/api/network-status": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Check public network graph, sitemap registration, and BrowserOps trust status",
        "responses": {
          "200": {
            "description": "Live bounded network evidence in the standard response envelope"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get public-safe service health",
        "responses": {
          "200": {
            "description": "Health response"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get versioned public-safe health",
        "responses": {
          "200": {
            "description": "Health response"
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get this OpenAPI document as JSON",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 JSON"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "tags": [
          "Platform"
        ],
        "summary": "Get MCP transport metadata",
        "responses": {
          "200": {
            "description": "MCP metadata and usage"
          }
        }
      },
      "post": {
        "tags": [
          "Platform"
        ],
        "summary": "Call the read-only DamWatch USA JSON-RPC MCP server",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  },
                  {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "$ref": "#/components/schemas/JsonRpcRequest"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response or batch"
          },
          "204": {
            "description": "Notification accepted without response"
          },
          "400": {
            "description": "Malformed JSON or invalid batch"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PlatPhormBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Reserved for future protected mutations; use PLATPHORM_API_KEY."
      },
      "PlatPhormHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "Reserved for future protected mutations; use PLATPHORM_API_KEY."
      }
    },
    "schemas": {
      "SuccessResponse": {
        "type": "object",
        "required": [
          "ok",
          "data"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "data": {
            "type": "object"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "details"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object"
              }
            }
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "additionalProperties": false,
        "properties": {
          "jsonrpc": {
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "type": "string"
          },
          "params": {
            "type": "object"
          }
        }
      }
    },
    "responses": {
      "ErrorResponse": {
        "description": "Structured error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "x-platphorm": {
    "service": "platphorm-dam",
    "creator": "Michael Barbine",
    "publisher": "PlatPhorm News",
    "authEnvironmentVariable": "PLATPHORM_API_KEY",
    "publicReadOnly": true,
    "mutationsImplemented": false,
    "publicCapabilities": {
      "count": 9,
      "items": [
        "interactive map and learning pages",
        "curated educational dam records",
        "bounded public USACE NID queries",
        "live NID inventory counts",
        "source and integration catalogs",
        "health, route compliance, and network evidence",
        "OpenAPI and discovery documents",
        "RSS and Atom feeds",
        "MCP introspection and read-only tools"
      ]
    },
    "protectedActions": {
      "count": 9,
      "items": [
        "mutations",
        "ingestion",
        "publishing",
        "replay and fork",
        "workflow runs",
        "browser and eval test triggers",
        "report generation",
        "registry or trusted-domain changes",
        "deployment and administrative actions"
      ]
    },
    "mcp": {
      "methods": [
        "initialize",
        "ping",
        "tools/list",
        "tools/call",
        "resources/list",
        "resources/read",
        "prompts/list",
        "prompts/get"
      ],
      "counts": {
        "tools": 5,
        "resources": 4,
        "prompts": 2
      }
    },
    "upstreamPolicy": "Only the fixed public USACE NID Feature Service is queried; arbitrary URL proxying is not supported."
  }
}