api.yml

openapi: 3.0.3
info:
  title: OpenEVSE WiFi API
  description: |
    The API for the OpenEVSE WiFi module
  version: '1.0'
  contact:
    email: jeremy@bigjungle.net
    name: Jeremy Poulter
    url: 'https://github.com/jeremypoulter/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: '{server}'
    variables:
      server:
        default: 'http://openevse.local'
  - url: 'http://localhost:8080'
paths:
  /status:
    get:
      operationId: getStatus
      summary: Get the EVSE status
      description: |
        The status endpoint can be called to get the status of the EVSE.

        While it is posible to poll this endpoint, the recomendatoin is to retrieve the initial
        state then use the [/ws](#statusUpdates)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./models/Status.yaml
              examples:
                EVSE Status:
                  value:
                    mode: STA
                    wifi_client_connected: 1
                    eth_connected: 0
                    net_connected: 1
                    srssi: -73
                    ipaddress: 192.168.1.43
                    emoncms_connected: 1
                    packets_sent: 22307
                    packets_success: 22290
                    mqtt_connected: 1
                    ohm_hour: NotConnected
                    free_heap: 203268
                    comm_sent: 335139
                    comm_success: 335139
                    rapi_connected: 1
                    amp: 0
                    pilot: 32
                    max_current: 32
                    temp1: 282
                    temp2: -2560
                    temp3: -2560
                    state: 254
                    elapsed: 3473
                    session_energy: 25034
                    total_energy: 998
                    total_day: 23
                    total_week: 68
                    total_month: 126
                    total_year: 998
                    gfcicount: 0
                    nogndcount: 0
                    stuckcount: 0
                    divertmode: 1
                    solar: 390
                    grid_ie: 0
                    charge_rate: 7
                    divert_update: 0
                    ota_update: 0
                    time: '2020-05-12T17:53:48Z'
                    offset: '+0000'
      tags:
        - Status
    post:
      operationId: postStatus
      summary: Update external data to EVSE status
      description: |
        The status endpoint can be called to post external data that should be updated by MQTT
        If MQTT is not an option, all external data needed can be updated from an HTTP POST request to /status endpoint.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  voltage:
                    type: integer
                    description: live voltage in V
                  shaper_live_pwr:
                    type: integer
                    description: total household live power in W
                  solar:
                    type: integer
                    description: divert solar production in W
                  grid_ie:
                    type: integer
                    description: divert grid -import/+export in W
                  battery_level:
                    type: integer
                    description: vehicle soc in %
                  battery_range:
                    type: integer
                    description: vehicle range
                  time_to_full_charge:
                    type: integer
                    description: vehicle charge ETA
                x-examples:
                  EVSE Status:
                    voltage: 220
                    shaper_live_pwr: 3400
                    solar: 3000
                    grid_ie: 3000
                    battery_level: 85
                    battery_range: 230
                    time_to_full_charge: 1590
              examples:
                EVSE Status:
                  value:
                    voltage: 220
                    shaper_live_pwr: 3400
                    solar: 3000
                    grid_ie: 3000
                    battery_level: 85
                    battery_range: 230
                    time_to_full_charge: 1590
      tags:
        - Status
  /ws:
    get:
      operationId: statusUpdates
      summary: EVSE status updates
      description: |
        As the state changes on the EVSE a websocket frame will be sent over the socket.
        The frame will contain a JSON document conntaining only the updated state.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./models/Status.yaml
        '400':
          description: Error
      tags:
        - Status
  /config:
    get:
      operationId: getConfig
      summary: Get the EVSE configuration
      description: |
        Retrieve the current WiFi and EVSE module configuration
      tags:
        - Config
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./models/Config.yaml
              examples: {}
    post:
      operationId: updateConfig
      responses:
        '200':
          $ref: '#/components/responses/UpdateSuccessful'
        '400':
          $ref: '#/components/responses/BadRequest'
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./models/Config.yaml
            examples:
              Update EmonCMS setting:
                value:
                  emoncms_enabled: true
                  emoncms_server: 'http://emoncms.org'
                  emoncms_node: openevse-a7d4
                  emoncms_apikey: emoncmskey
                  emoncms_fingerprint: ''
              Configure Solar divert:
                value:
                  divert_type: 0
                  divert_enabled: true
                  divert_attack_smoothing_time: 8
                  divert_decay_smoothing_time: 300
                  divert_min_charge_time: 20
              Set normal charging mode:
                value:
                  charge_mode: fast
              Set Eco mode:
                value:
                  charge_mode: eco
              Configure Tesla credentials:
                value:
                  tesla_enabled: true
                  tesla_access_token: qts-1234.......
                  tesla_refresh_token: abcd.......
                  tesla_created_at: 1623358948
                  tesla_expires_in: 3888000
              Select Tesla vehicle:
                value:
                  tesla_vehicle_id: '2238974987235987'
      summary: Update the EVSE configuration
      tags:
        - Config
  /override:
    description: Manual override can be used to override a charging timer or to immediately start a charge if the EVSE is in sleeping state.
    get:
      responses:
        '200':
          description: Manual overide is active
          content:
            application/json:
              schema:
                $ref: ./models/Properties.yaml
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getManualOverride
      tags:
        - Manual Override
      summary: Get the Manual Override status
      description: Returns the current state of the manual override.
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./models/Properties.yaml
            examples:
              Force stop of charging:
                value:
                  state: disabled
              example-1:
                value:
                  state: active
                  charge_current: 0
                  max_current: 0
                  auto_release: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
      operationId: setManualOverride
      tags:
        - Manual Override
      summary: Set the manual override
    patch:
      description: Toggle the manual override
      responses:
        '200':
          description: OK
      operationId: toggleManualOverride
      tags:
        - Manual Override
      summary: Toggle the manual Override
    delete:
      description: Clears the manual override
      responses:
        '200':
          description: OK
      operationId: clearManualOverride
      tags:
        - Manual Override
      summary: Clear the manual override
  /claims:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: ./models/Claim.yaml
      operationId: listClaims
      tags:
        - Claims
      summary: List EVSE claims
  '/claims/{client}':
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./models/Properties.yaml
        '404':
          $ref: '#/components/responses/NotFound'
      parameters: []
      operationId: getClaim
      tags:
        - Claims
      summary: Get EVSE claim information
    post:
      description: Make/Update a claim
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./models/Properties.yaml
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: setClaim
      summary: Make/Update an EVSE claim
      tags:
        - Claims
    delete:
      description: Release a claim
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: releaseClaim
      summary: Release an EVSE claim
      tags:
        - Claims
    parameters:
      - schema:
          type: integer
        name: client
        in: path
        required: true
        description: 'The client ID, defined by [OpenEVSE](https://github.com/OpenEVSE/openevse_esp32_firmware/blob/master/src/evse_man.h#L28)'
  /schedule:
    get:
      summary: List schedule events
      description: This will get a complete list of events in the schedule
      responses:
        '200':
          description: List of the schedule events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduleEvent'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: listSchedule
      tags:
        - Schedule
    post:
      operationId: updateSchedule
      description: Perform multiple event updates
      responses:
        '201':
          description: item created
        '400':
          description: 'invalid input, object invalid'
        '409':
          description: an existing item already exists
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ScheduleEvent'
            examples:
              Single event:
                value:
                  - id: 1
                    state: active
                    time: '14:15:22Z'
                    days:
                      - monday
              Daily Timer:
                value:
                  - id: 1
                    state: active
                    days:
                      - monday
                      - tuesday
                      - wednesday
                      - thursday
                      - friday
                      - saturday
                      - sunday
                    time: '07:00:00'
                  - id: 2
                    state: disabled
                    days:
                      - monday
                      - tuesday
                      - wednesday
                      - thursday
                      - friday
                      - saturday
                      - sunday
                    time: '10:00:00'
        description: Inventory item to add
      tags:
        - Schedule
      summary: Batch update schedule
  '/schedule/{id}':
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: Numeric ID of the event
    get:
      summary: Get event details
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: ./models/EvseState.yaml
      operationId: getScheduleEvent
      tags:
        - Schedule
    post:
      responses:
        '200':
          $ref: '#/components/responses/UpdateSuccessful'
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./models/EvseState.yaml
        description: ''
      operationId: setScheduleEvent
      tags:
        - Schedule
      summary: Update event details
    delete:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples: {}
      operationId: removeScheduleEvent
      tags:
        - Schedule
      summary: Remove event
  /schedule/plan:
    get:
      summary: Get planned events and state
      description: This will return the planned events by day and also the current state of the scheduler
      responses:
        '200':
          description: List of planed events
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_day:
                    $ref: '#/components/schemas/Day'
      operationId: getSchedulePlan
      tags:
        - Schedule
  /logs:
    get:
      summary: Get event block information
      tags:
        - Event Log
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  min:
                    type: integer
                  max:
                    type: integer
      operationId: getEventBlockInfo
      description: 'Retrieve the start and end indexes of the log event blocks. Each log event block contains '
      parameters: []
    parameters: []
  '/logs/{index}':
    get:
      summary: Get log block events
      tags:
        - Event Log
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEvent'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getEventBlock
      description: ''
    parameters:
      - schema:
          type: integer
        name: index
        in: path
        required: true
  /restart:
    post:
      summary: restart gateway or evse modules
      description: restart wifi gateway or openevse module
      operationId: restart
      tags:
        - Restart
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device:
                  type: string
                  description: gateway|evse
      responses:
        '200':
          description: Restart successfull
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: restart gateway|evse
  /limit:
    get:
      summary: Get charge limit
      description: 'This will return the limit type, value and auto_release (true|false) defined if there''s one'
      responses:
        '200':
          description: Limit properties
          content:
            application/json:
              schema:
                $ref: ./models/Limit.yaml
        '404':
          description: No limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: No limit
      operationId: limit_get
      tags:
        - Limit
    post:
      summary: Set charge limit
      description: 'This will set the limit type, value and auto_release (true|false)'
      responses:
        '200':
          description: Limit set
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: created
        '500':
          description: Failed to parse data
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Failed to parse JSON
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./models/Limit.yaml
      operationId: limit_set
      tags:
        - Limit
    delete:
      summary: Get charge limit
      description: This will clear current limit
      responses:
        '200':
          description: Clear Limit ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Deleted
        '404':
          description: No limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: No limit to clear
        '500':
          description: Failed to clear limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Failed to clear limit
      operationId: limit_clear
      tags:
        - Limit
  /emeter:
    delete:
      summary: Reset Energy Meter
      description: This will clear the Energy Meter
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                hard:
                  type: integer
                  description: 0|1 Enable hard reset ( reset total_counter & total_switches)
                import:
                  type: integer
                  description: 0|1 Import OpenEvse module total kwh.
      responses:
        '200':
          description: Reset counter ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Reset done
        '500':
          description: Failed to reset counter
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Reset failed
      operationId: energymeter-reset
      tags:
        - Energy Meter
  /tesla/vehicles:
    get:
      summary: Get Tesla vehicle list
      tags:
        - Tesla
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    count: 3
                    vehicles:
                      - id: '1492932278133304'
                        name: AwesomeSAUCE
                      - id: '1492931610165415'
                        name: Herbie
                      - id: '1492930973960452'
                        name: 'Life, the Universe, and Everything'
                properties:
                  count:
                    type: number
                  vehicles:
                    type: array
                    uniqueItems: true
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          minLength: 1
                        name:
                          type: string
                          minLength: 1
                      required:
                        - id
                        - name
                required:
                  - count
                  - vehicles
              examples:
                example-1:
                  value:
                    count: 1
                    vehicles:
                      - id: '2238974987235987'
                        name: My Tesla
      operationId: get-tesla-vehicles
      description: Once the Tesla account credentials have been configured via the `/config` API this endpoint will return a list of vehicles associated with the account. The ID of the vehicle to use for SoC/Range can then be set using `tesla_vehicle_id` on the `/config` endpoint.
  /time:
    get:
      summary: Get the time
      tags:
        - Time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  time:
                    type: string
                    x-stoplight:
                      id: 6q0laeyxt5u85
                    description: The time in UTC according to the OpenEVSE.
                    format: date-time
                  offset:
                    type: string
                    x-stoplight:
                      id: u5zngl88caktf
                    pattern: '^[+-][0-9]{4}$'
                  local_time:
                    type: string
                    x-stoplight:
                      id: 7h1cpgfjj5j9j
                    format: date-time
                  uptime:
                    type: integer
                    description: EVSE gateway uptime, in seconds
                required:
                  - time
                  - offset
                  - local_time
                  - uptime
      operationId: get-time
      description: Gets the time set on the OpenEVSE
    post:
      summary: Set the time
      tags:
        - Time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    sntp_enabled: false
                    time_zone: 'GMT0BST,M3.5.0/1,M10.5.0'
                    time: '2018-08-10T14:30:00Z'
                properties:
                  sntp_enabled:
                    type: boolean
                    description: |
                      Set to `true` to enable receiving time updates via NTP, `false` will disable NTP updates.
                    default: false
                  time_zone:
                    type: string
                    description: The time zone to use on the OpenEVSE. This has the format `<location name>|<POSIX timezone>`. The `location name` is not used by the EVSE and is largely to for the UI to provide a human readable version of the timezone and differentiate between locations that use the same time zone.
                    default: UTC0
                  time:
                    type: string
                    description: If `sntp_enabled` is false this is the time to set. Must be in UTC.
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: post-time
      description: Set the time and associated config options. If not setting the time the `/config` endpoint can be used.
components:
  schemas:
    Message:
      title: Informational message
      type: object
      properties:
        msg:
          type: string
          description: The message
    Day:
      type: string
      enum:
        - monday
        - tuesday
        - wednesday
        - thursday
        - friday
        - saturday
        - sunday
      x-examples: {}
    ScheduleEvent:
      type: object
      properties:
        id:
          type: integer
          example: 1
        state:
          $ref: ./models/EvseState.yaml
        time:
          type: string
          format: time
        days:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Day'
      required:
        - state
        - time
        - days
      title: ''
    LogEvent:
      title: LogEvent
      type: object
      x-examples:
        example-1:
          value:
            time: '2021-08-24T14:15:22Z'
            type: information
            managerState: active
            evseState: 1
            evseFlags: 123
            pilot: 32
            energy: 1234.5
            elapsed: 123456
            temperature: 35.4
            tempuratureMax: 50.4
            divertMode: 1
      properties:
        time:
          type: string
          format: date-time
          readOnly: true
        type:
          type: string
          enum:
            - information
            - notification
            - warning
        managerState:
          $ref: ./models/EvseState.yaml
        evseState:
          type: integer
          minimum: 0
          maximum: 255
        evseFlags:
          type: integer
          format: int32
        pilot:
          type: integer
          format: int32
          minimum: 0
        energy:
          type: number
          format: double
          minimum: 0
        elapsed:
          type: integer
          format: int32
          minimum: 0
        temperature:
          type: number
          format: double
        tempuratureMax:
          type: number
          format: double
        divertMode:
          type: integer
          format: int32
          minimum: 1
          maximum: 2
          exclusiveMaximum: false
  responses:
    UpdateSuccessful:
      description: Update successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
          examples:
            Success message:
              value:
                msg: done
    NotFound:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
          examples:
            Not found:
              value:
                msg: Not found
    BadRequest:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'
          examples:
            Bad JSON:
              value:
                msg: Could not parse JSON
  parameters: {}
tags:
  - name: Claims
  - name: Config
  - name: Event Log
  - name: Manual Override
  - name: Schedule
  - name: Status
  - name: Tesla
  - name: Limit
  - name: Energy Meter
  - name: Time
  - name: Restart