openapi: 3.0.3
info:
  title: USACE CWMS Data Catalog Levels 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: Levels
paths:
  /levels:
    get:
      operationId: getLevels
      summary: Get Location Levels
      description: Retrieves location levels (stage, elevation thresholds) for CWMS locations.
      tags:
      - Levels
      parameters:
      - name: location-id-mask
        in: query
        required: false
        description: Filter by location ID pattern
        schema:
          type: string
      - name: office
        in: query
        required: false
        description: Filter by office
        schema:
          type: string
      - name: unit
        in: query
        required: false
        description: Unit system
        schema:
          type: string
      - name: datum
        in: query
        required: false
        description: Vertical datum
        schema:
          type: string
      - name: begin
        in: query
        required: false
        description: Start time filter
        schema:
          type: string
      - name: end
        in: query
        required: false
        description: End time filter
        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: Location levels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LevelsResponse'
components:
  schemas:
    LevelsResponse:
      type: object
      properties:
        page:
          type: string
        next-page:
          type: string
        location-levels:
          type: array
          items:
            type: object
            properties:
              location-level-id:
                type: string
              office-id:
                type: string
              constant-value:
                type: number
              level-units-id:
                type: string
              level-date:
                type: string
              level-comment:
                type: string