Enphase Energy System Configurations API

openapi: 3.2.0
info:
  title: Monitoring System Configurations API
  version: v4
servers:
- url: https://api-qa2.enphaseenergy.com
tags:
- name: System Configurations
paths:
  /api/v4/systems/config/{system_id}/battery_settings:
    get:
      summary: Returns the current battery settings of a system
      description: Returns the current battery settings of a system
      parameters:
      - name: system_id
        in: path
        description: The unique numeric id of the system
        required: true
        schema:
          type: string
      tags:
      - System Configurations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                  battery_mode:
                    type: string
                    description: Current battery mode of the system. Possible values are Savings Mode, Full Backup, and Self - Consumption
                  reserve_soc:
                    type: integer
                    description: Reserve soc for the current mode
                  energy_independence:
                    type: string
                    description: 'Energy independence after peak hours enabled/disabled . Enabled: Battery will discharge to save money during peak hours when electricity rates are high. Once that is done, energy independence is prioritized. This will increase the energy self-sufficiency until the reserve soc is hit. Battery will charge from solar in the morning to get ready for the next period Disabled: Battery will discharge only during peak hours when electricity rates are high. During other times, battery will be idle or will charge from solar in the morning to get ready for the next period'
                  charge_from_grid:
                    type: string
                    description: 'Charge battery from grid enabled/disabled. Enabled: Battery may also charge from the grid when in full backup mode or when battery charge is below the reserve capacity in savings or self-consumption mode'
                  battery_shutdown_level:
                    type: integer
                    description: Level at which battery shutdowns to conserve energy. Battery restarts by using the conserved energy when the utility grid restores power or solar panels start producing energy
              example:
                system_id: 1765
                battery_mode: Self - Consumption
                reserve_soc: 95
                energy_independence: enabled
                charge_from_grid: disabled
                battery_shutdown_level: 13
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Authorized
                details: User is not authorized
                code: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Forbidden
                details: Not authorized to access this resource
                code: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Found
                details: System not found for {:id=>"1"}
                code: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Unprocessable Entity
                details: System doesn't have encharges
                code: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
                  period:
                    type: string
                    description: Quota exceeded for minute/month
                  period_start:
                    type: integer
                    description: Starting period timestamp
                  period_end:
                    type: integer
                    description: Ending period timestamp
                  limit:
                    type: integer
                    description: Limit count for the period
              example:
                message: Too Many Requests
                details: Usage limit exceeded for plan Kilowatt
                code: 429
                period: minute
                period_start: 1623825660
                period_end: 1623825720
                limit: 5
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
    put:
      summary: Updates the current battery settings of a system
      description: Updates the current battery settings of a system.
      parameters:
      - name: system_id
        in: path
        description: The unique numeric id of the system
        required: true
        schema:
          type: string
      tags:
      - System Configurations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                  battery_mode:
                    type: string
                    description: Current battery mode of the system
                  reserve_soc:
                    type: integer
                    description: Reserve soc for the current mode
                  energy_independence:
                    type: string
                    description: 'Energy independence after peak hours enabled/disabled . Enabled: Battery will discharge to save money during peak hours when electricity rates are high. Once that is done, energy independence is prioritized. This will increase the energy self-sufficiency until the reserve soc is hit. Battery will charge from solar in the morning to get ready for the next period Disabled: Battery will discharge only during peak hours when electricity rates are high. During other times, battery will be idle or will charge from solar in the morning to get ready for the next period'
                  charge_from_grid:
                    type: string
                    description: 'Charge battery from grid enabled/disabled. Enabled: Battery may also charge from the grid when in full backup mode or when battery charge is below the reserve capacity in savings or self-consumption mode'
                  battery_shutdown_level:
                    type: integer
                    description: Level at which battery shutdowns to conserve energy. Battery restarts by using the conserved energy when the utility grid restores power or solar panels start producing energy
              example:
                system_id: 1765
                battery_mode: self-consumption
                reserve_soc: 95
                energy_independence: enabled
                charge_from_grid: disabled
                battery_shutdown_level: 13
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Authorized
                details: User is not authorized
                code: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Forbidden
                details: Not authorized to access this resource
                code: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Found
                details: System not found for {:id=>"1"}
                code: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Unprocessable Entity
                details: System doesn't have encharge
                code: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
                  period:
                    type: string
                    description: Quota exceeded for minute/month
                  period_start:
                    type: integer
                    description: Starting period timestamp
                  period_end:
                    type: integer
                    description: Ending period timestamp
                  limit:
                    type: integer
                    description: Limit count for the period
              example:
                message: Too Many Requests
                details: Usage limit exceeded for plan Kilowatt
                code: 429
                period: minute
                period_start: 1623825660
                period_end: 1623825720
                limit: 5
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                battery_mode:
                  type: string
                  description: To update battery mode of the system (case sensitive) - "Savings Mode" / "Self-consumption" / "Full Backup"
                reserve_soc:
                  type: integer
                  description: Reserve soc for the current mode - cannot be less than vls
                energy_independence:
                  type: string
                  description: 'Energy independence after peak hours "enabled"/"disabled" . Enabled: Battery will discharge to save money during peak hours when electricity rates are high. Once that is done, energy independence is prioritized. This will increase the energy self-sufficiency until the reserve soc is hit. Battery will charge from solar in the morning to get ready for the next period Disabled: Battery will discharge only during peak hours when electricity rates are high. During other times, battery will be idle or will charge from solar in the morning to get ready for the next period'
  /api/v4/systems/config/{system_id}/storm_guard:
    get:
      summary: Returns the current storm guard settings of a system
      description: Returns the current storm guard settings of a system
      parameters:
      - name: system_id
        in: path
        description: The unique numeric id of the system
        required: true
        schema:
          type: string
      tags:
      - System Configurations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                  storm_guard_status:
                    type: string
                    description: Overrides your battery profile to full backup mode when a severe weather condition alert is issued in the localitym
                  storm_alert:
                    type: string
                    description: True if severe weather condition alert is issued in the locality
              example:
                system_id: 1765
                storm_guard_status: enabled
                storm_alert: 'false'
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Authorized
                details: User is not authorized
                code: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Forbidden
                details: Not authorized to access this resource
                code: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Found
                details: System not found for {:id=>"1"}
                code: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Unprocessable Entity
                details: System doesn't have encharges
                code: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
                  period:
                    type: string
                    description: Quota exceeded for minute/month
                  period_start:
                    type: integer
                    description: Starting period timestamp
                  period_end:
                    type: integer
                    description: Ending period timestamp
                  limit:
                    type: integer
                    description: Limit count for the period
              example:
                message: Too Many Requests
                details: Usage limit exceeded for plan Kilowatt
                code: 429
                period: minute
                period_start: 1623825660
                period_end: 1623825720
                limit: 5
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
    put:
      summary: Updates the current storm guard settings of a system
      description: Updates the current storm guard status of a system.
      parameters:
      - name: system_id
        in: path
        description: The unique numeric id of the system
        required: true
        schema:
          type: string
      tags:
      - System Configurations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                  storm_guard_status:
                    type: string
                    description: Overrides your battery profile to full backup mode when a severe weather condition alert is issued in the locality
                  storm_alert:
                    type: string
                    description: True if severe weather condition alert is issued in the locality
              example:
                system_id: 1765
                storm_guard_status: Enabled (Inactive)
                storm_alert: 'false'
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Authorized
                details: User is not authorized
                code: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Forbidden
                details: Not authorized to access this resource
                code: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Found
                details: System not found for {:id=>"1"}
                code: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Unprocessable Entity
                details: System doesn't have encharge
                code: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
                  period:
                    type: string
                    description: Quota exceeded for minute/month
                  period_start:
                    type: integer
                    description: Starting period timestamp
                  period_end:
                    type: integer
                    description: Ending period timestamp
                  limit:
                    type: integer
                    description: Limit count for the period
              example:
                message: Too Many Requests
                details: Usage limit exceeded for plan Kilowatt
                code: 429
                period: minute
                period_start: 1623825660
                period_end: 1623825720
                limit: 5
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '501'
                message:
                - Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                storm_guard_status:
                  type: string
                  description: Overrides your battery profile to full backup mode when a severe weather condition alert is issued in the locality, can be enabled/disabled
              required:
              - storm_guard_status
  /api/v4/systems/config/{system_id}/grid_status:
    get:
      summary: Returns the current grid status of a system
      description: Returns the current grid status of a system
      parameters:
      - name: system_id
        in: path
        description: The unique numeric id of the system
        required: true
        schema:
          type: string
      tags:
      - System Configurations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  system_id:
                    type: integer
                  grid_state:
                    type: string
                    description: Indicates whether the site is On Grid, Off Grid or grid status of site is Unknown
                  last_report_date:
                    type: integer
                    description: Timestamp (in epoch format) at which the system's Envoy last submitted a report
              example:
                system_id: 1765
                grid_state: On Grid
                last_report_date: 1676029267
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Authorized
                details: User is not authorized
                code: 401
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Forbidden
                details: Not authorized to access this resource
                code: 403
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Not Found
                details: System not found for {:id=>"1"}
                code: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                  message:
                    type: array
                    items:
                      type: string
              example:
                reason: '405'
                message:
                - Method not allowed
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    description: Error Details
                  code:
                    type: integer
                    description: Error Code
              example:
                message: Unprocessable Entity
                details: grid_state not available as the site has not reported yet
                code: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error Type
                  details:
                    type: string
                    descri

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/enphase/refs/heads/main/openapi/enphase-system-configurations-api-openapi.yml