openapi: 3.0.3
info:
  title: USACE CWMS Data Catalog Reservoirs API
  description: The Corps Water Management System (CWMS) Data API (CDA) is a RESTful API that enables secure data exchange for publicly available USACE water management data. The API provides access to timeseries data, location information, ratings, reservoirs, levels, and other water resource data maintained by the US Army Corps of Engineers.
  version: 2.0.0
  contact:
    name: USACE HEC
    url: https://cwms-data.usace.army.mil/cwms-data/
  license:
    name: Public Domain
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://cwms-data.usace.army.mil/cwms-data
  description: Production server (public data)
- url: https://cwms-data-test.cwbi.us/cwms-data
  description: Test server
tags:
- name: Reservoirs
paths:
  /reservoirs:
    get:
      operationId: getReservoirs
      summary: Get Reservoir Projects
      description: Returns USACE reservoir project information, including pool data and storage.
      tags:
      - Reservoirs
      parameters:
      - name: office
        in: query
        required: false
        description: Filter by office
        schema:
          type: string
      - name: project-id-like
        in: query
        required: false
        description: Filter by project ID pattern
        schema:
          type: string
      - name: page-size
        in: query
        required: false
        schema:
          type: integer
      - name: page
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of reservoirs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservoirsResponse'
components:
  schemas:
    ReservoirsResponse:
      type: object
      properties:
        page:
          type: string
        next-page:
          type: string
        reservoirs:
          type: array
          items:
            type: object
            properties:
              project-id:
                type: object
                properties:
                  name:
                    type: string
                  office-id:
                    type: string
              near-normal-storage:
                type: number
              normal-storage-period:
                type: string