openapi: 3.0.3
info:
  title: EcoFlow IoT Open Platform Devices Quota API
  description: The EcoFlow IoT Open Platform (developer.ecoflow.com) HTTP API lets registered developers read telemetry from and send control commands to EcoFlow devices (portable power stations, Delta/River series, PowerStream micro-inverters, smart plugs, Power Kits and more) that are bound to a user account. Access is authenticated with an accessKey / secretKey pair issued in the developer console; every request carries an HMAC-SHA256 `sign` header computed over the sorted request parameters plus `accessKey`, `nonce` and `timestamp`. Real-time streaming and command delivery is handled over MQTT (see the companion AsyncAPI); this HTTP surface covers device discovery, a snapshot of all device "quota" (property) values, targeted quota queries, device function commands, and retrieval of the MQTT connection certificate.
  version: '1.0'
  contact:
    name: EcoFlow Developer Platform
    url: https://developer.ecoflow.com
  x-source: Endpoint surface, headers and signing verified from EcoFlow developer portal (developer.ecoflow.com / developer-eu.ecoflow.com) and independent public-API client implementations (github.com/tolwi/hassio-ecoflow-cloud).
servers:
- url: https://api.ecoflow.com
  description: Global / US region
- url: https://api-e.ecoflow.com
  description: Europe region
security:
- accessKey: []
  nonce: []
  timestamp: []
  sign: []
tags:
- name: Quota
  description: Read device property (quota) values and send device function commands
paths:
  /iot-open/sign/device/quota/all:
    get:
      operationId: getAllQuota
      summary: Get all quota for a device
      description: Returns a full snapshot of every property ("quota") value the specified device currently reports (battery %, input/output watts, switch states, temperatures, etc.). The `data` object is a flat map of dotted quota keys to values and varies by product line.
      tags:
      - Quota
      parameters:
      - name: sn
        in: query
        required: true
        description: Device serial number
        schema:
          type: string
      responses:
        '200':
          description: Quota snapshot retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /iot-open/sign/device/quota:
    post:
      operationId: getQuota
      summary: Get selected quota values
      description: Returns only the requested property ("quota") values for a device. Supply the device serial and the list of dotted quota keys to read.
      tags:
      - Quota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuotaRequest'
            example:
              sn: R331ZEB4ZEAL0000
              params:
                quotas:
                - pd.soc
                - inv.outputWatts
      responses:
        '200':
          description: Selected quota retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      operationId: setQuota
      summary: Set a device function (command)
      description: Sends a control command to a device by setting one or more of its function parameters. The `moduleType`, `operateType` and `params` shape is product-specific (e.g. set AC output on/off, set charge speed, set buzzer). Commands are also deliverable over the MQTT `set` topic.
      tags:
      - Quota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetQuotaRequest'
            example:
              sn: R331ZEB4ZEAL0000
              moduleType: 1
              operateType: acOutCfg
              params:
                enabled: 1
      responses:
        '200':
          description: Command accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
              example:
                code: '0'
                message: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CommandResponse:
      $ref: '#/components/schemas/Envelope'
    QuotaResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
            additionalProperties: true
            description: Flat map of dotted quota keys to their current values.
    Envelope:
      type: object
      description: Standard EcoFlow response envelope.
      properties:
        code:
          type: string
          description: Result code; "0" indicates success, any other value is an error.
        message:
          type: string
          description: Human-readable result message.
      required:
      - code
      - message
    GetQuotaRequest:
      type: object
      required:
      - sn
      - params
      properties:
        sn:
          type: string
          description: Device serial number.
        params:
          type: object
          properties:
            quotas:
              type: array
              items:
                type: string
              description: Dotted quota keys to read (e.g. pd.soc).
    SetQuotaRequest:
      type: object
      required:
      - sn
      properties:
        sn:
          type: string
          description: Device serial number.
        moduleType:
          type: integer
          description: Target module type (product-specific).
        operateType:
          type: string
          description: Operation/command name (product-specific).
        params:
          type: object
          additionalProperties: true
          description: Command parameters (product-specific).
    ErrorResponse:
      $ref: '#/components/schemas/Envelope'
  responses:
    Unauthorized:
      description: Authentication failed (bad accessKey, expired timestamp, or sign mismatch)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: '7000'
            message: Signature verification failed
    ServerError:
      description: Server-side error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: '500'
            message: System error
    BadRequest:
      description: Invalid request (bad parameters or malformed signature)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: '6001'
            message: Parameter error
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: accessKey
      description: Access key issued in the EcoFlow developer console.
    nonce:
      type: apiKey
      in: header
      name: nonce
      description: Random nonce (typically a 6-digit number) regenerated per request.
    timestamp:
      type: apiKey
      in: header
      name: timestamp
      description: Unix timestamp in milliseconds at request time.
    sign:
      type: apiKey
      in: header
      name: sign
      description: HMAC-SHA256 signature (hex) over the ASCII-sorted request parameters concatenated with `accessKey`, `nonce` and `timestamp`, keyed by the secretKey.