Zaptec Charger API

openapi: 3.2.0
info:
  title: Zaptec Charger API
  version: v1
servers:
- url: https://api.zaptec.com
tags:
- name: Charger
paths:
  /api/chargers:
    get:
      tags:
      - Charger
      summary: Chargers
      description: 'Retrieves all chargers accessible by the current user, matching the provided filters.

        By default, returns the first 50 items. Use `pageIndex` for pagination or adjust `pageSize` (max: 100).'
      operationId: api_chargers_get
      parameters:
      - name: Roles
        in: query
        description: 'Return only charge points where current user has any of the provided user roles. Note

          that this is a bit-flag and multiple roles can be provided.


          0 = None


          1 = User


          2 = Owner


          4 = Maintainer


          8 = Administrator


          15 = Any


          16 = Onboarding


          32 = DeviceAdministrator


          64 = PartnerAdministrator


          128 = Technical


          256 = InternalData'
        schema:
          $ref: '#/components/schemas/UserRoles'
      - name: DeviceType
        in: query
        description: 'Return only charge points of the provided type.


          0 = Unknown


          1 = Smart


          2 = Portable


          3 = HomeApm


          4 = Apollo


          5 = OtherApm


          6 = GenericApm


          7 = HanApm


          8 = TicApm'
        schema:
          $ref: '#/components/schemas/DeviceType'
      - name: InstallationType
        in: query
        description: 'Return only chargers installed in installations of this time.


          0 = Pro


          1 = Smart'
        schema:
          $ref: '#/components/schemas/InstallationTypeCode'
      - name: InstallationId
        in: query
        description: Return only chargers in the specified installation.
        schema:
          type: string
          format: uuid
      - name: NameFilter
        in: query
        description: 'A filter used to filter items. The filter may be applied to multiple

          properties depending on the object type.'
        schema:
          type: string
      - name: ReturnIdNameOnly
        in: query
        description: 'If true objects are only returned with their basic properties like

          Id and name.'
        schema:
          type: boolean
      - name: SortProperty
        in: query
        description: Name of the property used to sort the result.
        schema:
          type: string
      - name: SortDescending
        in: query
        description: Set to true to sort items in descending order.
        schema:
          type: boolean
      - name: PageSize
        in: query
        description: Number of items to return per page.
        schema:
          type: integer
          format: int32
      - name: PageIndex
        in: query
        description: The page index to return, first page is 0.
        schema:
          type: integer
          format: int32
      - name: IncludeDisabled
        in: query
        description: If true, and your user has access, include disabled objects.
        schema:
          type: boolean
      - name: Exclude
        in: query
        description: Get or set a list of item Id's that will be excluded from the result.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: PageInfoOnly
        in: query
        description: Returns only information about pages and no data info.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ChargerListModelPagedData'
            application/json:
              schema:
                $ref: '#/components/schemas/ChargerListModelPagedData'
            text/json:
              schema:
                $ref: '#/components/schemas/ChargerListModelPagedData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
  /api/chargers/{id}:
    get:
      tags:
      - Charger
      summary: Charger details
      description: Retrieves the specified charger (requires owner or service permissions).
      operationId: api_chargers_{id}_get
      parameters:
      - name: id
        in: path
        description: Charger ID
        required: true
        schema:
          type: string
          format: uuid
      - name: includeServiceLevelTechnicalReadAccess
        in: query
        description: 'Include Zaptec.ZapCloud.WebAPI.Models.ChargerListModel.CurrentUserHasServiceLevelTechnicalReadAccess:

          whether the current user is entitled to TechnicalRead (debug-log) access on this charger,

          granted through a user group that carries the TechnicalRead service-level entitlement and

          has an effective Owner permission on the charger (including inherited and wildcard targets).'
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ChargerListModel'
            application/json:
              schema:
                $ref: '#/components/schemas/ChargerListModel'
            text/json:
              schema:
                $ref: '#/components/schemas/ChargerListModel'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
  /api/chargers/{id}/update:
    post:
      tags:
      - Charger
      summary: Update charger
      description: 'Updates charger properties (requires owner or service permissions).


        Charge Current Settings:


        The `maxChargeCurrent` and `minChargeCurrent` properties should generally not be used. These are intended for special cases where an external party must override the Zaptec load balancer, which may cause unexpected behavior.


        It is recommended to control the charging system using the installation’s `AvailableCurrent` setting instead.


        Offline Current/Phase Override:


        Use only when charging stations must not automatically optimize offline current or phases.


        - Set `OfflineChargeCurrent` to `-1` to enable automatic allocation.


        - Any value between `0` and `32` overrides the automatic setting. `null` is ignored.


        - Set `OfflineChargePhase` to `0 (Phases.None)` to enable automatic allocation.


        - Any other valid value will override the automatic setting.


        Ensure that the total of all overridden values in an installation does not exceed the fuse limit.


        Meter Value Interval:


        Controls how often periodic energy data is reported.


        The recommended default is `30 minutes`. Setting this to `0` disables periodic reporting, affecting both session data and signed meter values.'
      operationId: api_chargers_{id}_update_post
      parameters:
      - name: id
        in: path
        description: Charger ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Charger properties to update
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/ChargerExternalUpdateModel'
          application/json:
            schema:
              $ref: '#/components/schemas/ChargerExternalUpdateModel'
          text/json:
            schema:
              $ref: '#/components/schemas/ChargerExternalUpdateModel'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ChargerExternalUpdateModel'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
  /api/chargers/{id}/state:
    get:
      tags:
      - Charger
      summary: Charger state
      description: 'Retrieves the current state properties (observations) for the specified charger

        (requires owner or service permissions).


        State IDs may vary by charger model.

        Current-generation ZapCharger Smart supports Observations from

        api/constants'
      operationId: api_chargers_{id}_state_get
      parameters:
      - name: id
        in: path
        description: Charger ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargerStateModel'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargerStateModel'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargerStateModel'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
  /api/chargers/{id}/sendCommand/{commandId}:
    post:
      tags:
      - Charger
      summary: Send charger command
      description: 'Permissions: Requires owner or service-level access.


        Supported Command IDs:


        - 102 – Restart the charger


        - 200 – Upgrade charger firmware


        - 506 – Stop or pause charging


        - 507 – Resume charging


        - 10001 – Deauthorize and stop charging


        Command 10001 – Deauthorize and Stop:


        The caller must ensure that no new charging sessions are authorized until the command is completed.


        Command 506 – Pause/Stop Charging:


        - Requires firmware version > 3.2 on PRO chargers


        - Typical usage: For chargers in active charging mode (state ChargeOperationMode, 710 = 3). Other edge cases are supported,

        but this is the most common scenario.


        - The command will be rejected if the charger is already paused (state ChargeOperationMode, 710 = 5 and FinalStopActive, 718 = 1)

        or disconnected (state ChargeOperationMode, 710 = 1)

        Commands 507 – Resume Charging:


        - Requires firmware version > 3.2 on PRO chargers


        - Typical usage: For chargers in paused state (state ChargeOperationMode, 710 = 5 and FinalStopActive, 718 = 1).

        Other edge cases are supported, but this is the most common scenario.


        - The command will be rejected if the charger is not in paused mode (state ChargeOperationMode, 710 = 5 and FinalStopActive, 718 = 1)


        neither Scheduler is active (state NextScheduleEvent, 763 is set)'
      operationId: api_chargers_{id}_sendcommand_{commandid}_post
      parameters:
      - name: id
        in: path
        description: Unique identifier of the charger.
        required: true
        schema:
          type: string
          format: uuid
      - name: commandId
        in: path
        description: The ID of the command to execute.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
components:
  schemas:
    ChargerExternalUpdateModel:
      type: object
      properties:
        maxChargeCurrent:
          type:
          - number
          - 'null'
          description: 'Adjustable between 0 and 32A. If charge current is below the charger minimum charge

            current (usually 6A), no charge current will be allocated.'
          format: double
        maxChargePhases:
          $ref: '#/components/schemas/MaxPhase'
        minChargeCurrent:
          type:
          - number
          - 'null'
          description: 'The minimum allocated charge current. If there is not enough current available to

            provide the chargers minimum current it will not be able to charge. Usually set to

            match the vehicle minimum current for charging (defaults to 6A).'
          format: double
        offlineChargeCurrent:
          type:
          - number
          - 'null'
          description: "Adjustable between 0 and 32A. If offline charge current is below the charger minimum charge\ncurrent (usually 6A), no charge current will be allocated when offline.\nOffline current override should only be done in special cases where charging \nstations should not automatically optimize offline current. In most cases \nthis setting should be set to -1 to allow ZapCloud to optimise offline current.\nIf -1, offline current will be automatically allocated."
          format: double
        offlineChargePhase:
          $ref: '#/components/schemas/Phases'
        meterValueInterval:
          type:
          - integer
          - 'null'
          description: 'The interval in seconds for a charger to report meter values.

            Defaults to 900 seconds for Pro and 3600 seconds for Go'
          format: int32
      additionalProperties: false
    ChargerOperatingMode:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 5
      type: integer
      description: '


        0 = Unknown


        1 = Disconnected


        2 = Connected_Requesting


        3 = Connected_Charging


        5 = Connected_Finished'
      format: int32
      x-enumNames:
      - Unknown
      - Disconnected
      - Connected_Requesting
      - Connected_Charging
      - Connected_Finished
    UserRoles:
      enum:
      - 0
      - 1
      - 2
      - 4
      - 8
      - 15
      - 16
      - 32
      - 64
      - 128
      - 256
      type: integer
      description: '


        0 = None


        1 = User


        2 = Owner


        4 = Maintainer


        8 = Administrator


        15 = Any


        16 = Onboarding


        32 = DeviceAdministrator


        64 = PartnerAdministrator


        128 = Technical


        256 = InternalData'
      format: int32
      x-enumNames:
      - None
      - User
      - Owner
      - Maintainer
      - Administrator
      - Any
      - Onboarding
      - DeviceAdministrator
      - PartnerAdministrator
      - Technical
      - InternalData
      x-enumFlags: true
    ChargerStateModel:
      type: object
      properties:
        chargerId:
          type: string
          format: uuid
        stateId:
          type: integer
          format: int32
        stateName:
          type:
          - string
          - 'null'
        timestamp:
          type: string
          format: date-time
        valueAsString:
          type:
          - string
          - 'null'
      additionalProperties: false
    InstallationAuthenticationType:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: '


        0 = Native


        1 = WebHooks


        2 = Ocpp


        3 = OcppNative'
      format: int32
      x-enumNames:
      - Native
      - WebHooks
      - Ocpp
      - OcppNative
    Phases:
      enum:
      - 0
      - 1
      - 2
      - 4
      - 7
      type: integer
      description: '


        0 = None


        1 = Phase_1


        2 = Phase_2


        4 = Phase_3


        7 = All'
      format: int32
      x-enumNames:
      - None
      - Phase_1
      - Phase_2
      - Phase_3
      - All
      x-enumFlags: true
    ChargerListModelPagedData:
      type: object
      properties:
        pages:
          type: integer
          format: int32
        totalCount:
          type: integer
          description: Total number of rows across all pages.
          format: int32
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ChargerListModel'
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    InstallationTypeCode:
      enum:
      - 0
      - 1
      type: integer
      description: '


        0 = Pro


        1 = Smart'
      format: int32
      x-enumNames:
      - Pro
      - Smart
    DeviceType:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      type: integer
      description: '


        0 = Unknown


        1 = Smart


        2 = Portable


        3 = HomeApm


        4 = Apollo


        5 = OtherApm


        6 = GenericApm


        7 = HanApm


        8 = TicApm'
      format: int32
      x-enumNames:
      - Unknown
      - Smart
      - Portable
      - HomeApm
      - Apollo
      - OtherApm
      - GenericApm
      - HanApm
      - TicApm
    MaxPhase:
      enum:
      - 1
      - 3
      type: integer
      description: '


        1 = One


        3 = Three'
      format: int32
      x-enumNames:
      - One
      - Three
    ChargerListModel:
      type: object
      properties:
        id:
          type: string
          description: Get the unique identifier of the charge point.
          format: uuid
        mid:
          type:
          - string
          - 'null'
          description: "<strong>This property is obsolete and is scheduled for removal,</strong>\n            please use `DeviceId` instead."
          readOnly: true
          deprecated: true
        deviceId:
          type:
          - string
          - 'null'
          description: Get the deviceId (serialNo) of the charging stations used with the charge point.
        serialNo:
          type:
          - string
          - 'null'
          description: "<strong>This property is obsolete and is scheduled for removal,</strong>\n            please use `Name` instead."
          readOnly: true
          deprecated: true
        name:
          type:
          - string
          - 'null'
          description: Get the name of the charge point.
        createdOnDate:
          type:
          - string
          - 'null'
          description: Get the date and time the installation was created.
          format: date-time
        circuitId:
          type:
          - string
          - 'null'
          description: Get the unique identifier the charge point is installed in.
          format: uuid
        active:
          type:
          - boolean
          - 'null'
          description: Get a value indicating whether the charge point is active.
        currentUserRoles:
          $ref: '#/components/schemas/UserRoles'
        pin:
          type:
          - string
          - 'null'
          description: 'Get the charger PIN code. This will only be provided if your user is system owner

            for the charge point.'
        templateId:
          type:
          - string
          - 'null'
          description: Get the unique identifier of the chargers firmware template.
          format: uuid
        propertyOcppUrl:
          type:
          - string
          - 'null'
        propertyOcppPassword:
          type:
          - string
          - 'null'
        propertyPinOfflinePhase:
          type:
          - boolean
          - 'null'
        propertyAuthenticationDisabled:
          type:
          - boolean
          - 'null'
        hasSessions:
          type:
          - boolean
          - 'null'
        propertyOfflinePhaseOverride:
          $ref: '#/components/schemas/Phases'
        propertyOfflineCurrentOverride:
          type:
          - number
          - 'null'
          format: double
        propertyOcppVerboseLogUntil:
          type:
          - string
          - 'null'
          format: date-time
        propertyOcppDefaultIdTag:
          type:
          - string
          - 'null'
        propertyOcppWebSocketPingInterval:
          type:
          - integer
          - 'null'
          format: int32
        propertyPrioritizedCurrent:
          type:
          - number
          - 'null'
          format: double
        propertyPrioritizedPhases:
          $ref: '#/components/schemas/MaxPhase'
        propertyMaxSinglePhaseChargeCurrent:
          type:
          - number
          - 'null'
          format: double
        propertyOcppAvailability:
          type:
          - integer
          - 'null'
          format: int32
        propertyOcppOfflineListVersion:
          type:
          - integer
          - 'null'
          format: int32
        signedMeterValueKwh:
          type:
          - number
          - 'null'
          format: double
        signedMeterValue:
          type:
          - string
          - 'null'
        signedSessionEichrecht:
          type:
          - string
          - 'null'
        deviceType:
          $ref: '#/components/schemas/DeviceType'
        installationName:
          type:
          - string
          - 'null'
        installationId:
          type:
          - string
          - 'null'
          format: uuid
        installationActive:
          type:
          - boolean
          - 'null'
        installationType:
          $ref: '#/components/schemas/InstallationTypeCode'
        authenticationType:
          $ref: '#/components/schemas/InstallationAuthenticationType'
        currentUserInstallationRoles:
          $ref: '#/components/schemas/UserRoles'
        isAuthorizationRequired:
          type:
          - boolean
          - 'null'
        currentUserHasServiceLevelTechnicalReadAccess:
          type:
          - boolean
          - 'null'
          description: 'Service-level entitlement flag (not a regular role/permission): `true` when the current

            user is entitled to TechnicalRead (debug-log) access on this charger. The entitlement is granted

            through a user group that carries the Zaptec.ZapCloud.Domain.Models.ServiceLevel.TechnicalRead service level and

            has an effective Owner permission on the charger (including inherited and wildcard targets).

            Used by the frontend to decide whether to surface relevant UI.

            `null` unless explicitly requested (opt-in).'
        operatingMode:
          $ref: '#/components/schemas/ChargerOperatingMode'
        isOnline:
          type: boolean
        warnings:
          type:
          - string
          - 'null'
      additionalProperties: false
  securitySchemes:
    ory_auth:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.zaptec.com/oauth/token
          scopes: {}