Zaptec Session API

openapi: 3.2.0
info:
  title: Zaptec Session API
  version: v1
servers:
- url: https://api.zaptec.com
tags:
- name: Session
paths:
  /api/sessions/archived:
    get:
      tags:
      - Session
      summary: Archived sessions
      description: 'Retrieves completed charge sessions accessible by the current user, filtered by date range and exactly one of: an installation, a single charger, or an authorized user (the calling user''s own id; support may pass any user''s id). Results are returned in cursor-paginated pages in the requested `order` (oldest first by default); when `hasMore` is true, send the returned `cursor` as `?cursor=` on the next request to fetch the next page. Default page size: 50. Max: 200.'
      operationId: api_sessions_archived_get
      parameters:
      - name: From
        in: query
        description: Inclusive lower bound for session end time. Required.
        schema:
          type: string
          format: date-time
      - name: To
        in: query
        description: Exclusive upper bound for session end time. Required, must be after `from`.
        schema:
          type: string
          format: date-time
      - name: InstallationId
        in: query
        description: 'Installation to list sessions for. Requires owner role on the installation.

          Exactly one of `installationId`, `chargerId` or `authorizedUserId` is required.'
        schema:
          type: string
          format: uuid
      - name: ChargerId
        in: query
        description: 'Single charger to list sessions for. Requires owner role on the charger.

          Exactly one of `installationId`, `chargerId` or `authorizedUserId` is required.'
        schema:
          type: string
          format: uuid
      - name: AuthorizedUserId
        in: query
        description: 'User whose sessions to list. Must be the id of the calling user, unless the caller

          has an Administrator permission covering that user (support access).

          Exactly one of `installationId`, `chargerId` or `authorizedUserId` is required.'
        schema:
          type: string
          format: uuid
      - name: PageSize
        in: query
        description: Page size. Default 50, max 200.
        schema:
          type: integer
          format: int32
      - name: Order
        in: query
        description: 'Sort order, by the time the session was recognized by the archive.

          Defaults to RecognizedTimeAscending (oldest first).


          0 = RecognizedTimeAscending


          1 = RecognizedTimeDescending'
        schema:
          $ref: '#/components/schemas/ArchivedSessionOrder'
        x-enumNames:
        - RecognizedTimeAscending
        - RecognizedTimeDescending
      - name: Cursor
        in: query
        description: Opaque cursor from a previous response's `cursor` field. Omit to start from the first page.
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArchivedSessionsResponse'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - ory_auth: []
  /api/session/{id}:
    get:
      tags:
      - Session
      summary: Session details
      description: Retrieves details for the specified charging session.
      operationId: api_session_{id}_get
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionEndData'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
  /api/session/{id}/priority:
    post:
      tags:
      - Session
      summary: Set session priority
      description: 'Assigns priority to a charging session (requires owner or service permissions).


        Prioritized sessions are allocated before unprioritized ones and will receive

        at least the prioritized current.


        Important considerations:


        - Multiple sessions can be prioritized; the caller must ensure enough available current.


        - If there is insufficient current, prioritized sessions are allocated on a first-come, first-served basis.


        - After allocating prioritized sessions, any remaining current is distributed among unprioritized sessions.'
      operationId: api_session_{id}_priority_post
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Priority level for the session
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/ChargePriority'
          application/json:
            schema:
              $ref: '#/components/schemas/ChargePriority'
          text/json:
            schema:
              $ref: '#/components/schemas/ChargePriority'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ChargePriority'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
components:
  schemas:
    ArchivedSessionOrder:
      enum:
      - 0
      - 1
      type: integer
      description: 'Sort order for archived sessions, by the time the session was recognized

        and finalized by the archive (see `recognizedDateTime`).


        0 = RecognizedTimeAscending


        1 = RecognizedTimeDescending'
      format: int32
      x-enumNames:
      - RecognizedTimeAscending
      - RecognizedTimeDescending
    GetArchivedSessionsResponse:
      required:
      - sessions
      type: object
      properties:
        sessions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ArchivedSession'
          description: The archived sessions on this page, in the requested `order` (oldest first by default).
        cursor:
          type:
          - string
          - 'null'
          description: 'Opaque cursor to fetch the next page. Send as `?cursor=` on the next

            request when `hasMore` is true. Null when there are no further pages.'
        hasMore:
          type: boolean
          description: True when more pages are available beyond this one.
      additionalProperties: false
      description: A page of archived charge sessions, with a cursor for fetching the next page.
    ChargePriority:
      type: object
      properties:
        prioritizedPhases:
          $ref: '#/components/schemas/MaxPhase'
        prioritizedCurrent:
          type:
          - number
          - 'null'
          format: double
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    ArchivedSession:
      required:
      - id
      - startDateTime
      type: object
      properties:
        id:
          type: string
          description: Unique session identifier.
          format: uuid
        externalId:
          type:
          - string
          - 'null'
          description: 'External identifier for the session when authorized by a third party

            (e.g. `transactionId` from OCPP). Null when not externally authorized.'
        replacedBySessionId:
          type:
          - string
          - 'null'
          description: 'If this session was superseded by a corrected one, the id of the replacement.

            Replaced sessions have no duration or energy and are marked as `voided`.'
          format: uuid
        authorizedUser:
          $ref: '#/components/schemas/ArchivedSessionUser'
        tokenName:
          type:
          - string
          - 'null'
          description: The RFID token used to authorize the session, when applicable.
        chargerId:
          type: string
          description: The charge point unique identifier.
          format: uuid
        deviceId:
          type:
          - string
          - 'null'
          description: The charge point device id.
        deviceName:
          type:
          - string
          - 'null'
          description: The charge point serial number / display name.
        chargerFirmwareVersion:
          type:
          - string
          - 'null'
          description: 'Charger firmware version at the time the session was recorded. Null for legacy

            sessions recorded before firmware version was tracked.'
        chargerDeviceType:
          type: integer
          description: The charge point device type (`Zaptec.ZapCloud.Core.DeviceType`).
          format: int32
        installationId:
          type:
          - string
          - 'null'
          description: The installation the charger belonged to when the session was recorded.
          format: uuid
        installationName:
          type:
          - string
          - 'null'
          description: The installation's display name. Null when the installation no longer exists.
        startDateTime:
          type: string
          description: 'Session start time. Time of session authorization. Usually corresponds within

            a few seconds to the connection time, but can be delayed if the user does not

            authorize immediately.'
          format: date-time
        endDateTime:
          type:
          - string
          - 'null'
          description: The actual end time of the session, as recorded by the archive.
          format: date-time
        recognizedDateTime:
          type: string
          description: Time the session was recognized and finalized by the archive.
          format: date-time
        offline:
          type: boolean
          description: True if the session was recorded while the charger was offline.
        reliableClock:
          type: boolean
          description: 'True if the charger''s clock was trusted at the time of recording. Relevant

            for offline sessions where start/end timestamps may otherwise be unreliable.'
        stoppedByRfid:
          type: boolean
          description: True if the session was stopped by presenting an RFID token.
        signed:
          type: boolean
          description: True if the session has an OCMF signed payload (see `sessionSignature`).
        voided:
          type: boolean
          description: 'True if the session was voided after creation, typically because it was

            replaced by a corrected session (see `replacedBySessionId`). Voided

            sessions have no meaningful duration or energy.'
        aborted:
          type: boolean
          description: True if the session was aborted (e.g. cable unplugged before charging started).
        ocppNative:
          type: boolean
          description: True if the session was driven by native OCPP authorization on the charger.
        externallyAbandoned:
          type: boolean
          description: True if an externally-authorized session was never acknowledged by the third party.
        sessionSignature:
          type:
          - string
          - 'null'
          description: OCMF signed session payload for supported charging stations.
        sessionSignatureEichreicht:
          type:
          - string
          - 'null'
          description: OCMF signed session payload in compliance with the German Eichrecht regulations.
        energy:
          type: number
          description: Energy delivered during the session, in kWh.
          format: double
        energyDetails:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ArchivedSessionEnergyPoint'
          description: 'Per-timestamp energy readings captured during the session. Empty when the

            archive has no detailed readings for this session.'
      additionalProperties: false
      description: A single completed (archived) charge session.
    ValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
      additionalProperties: {}
    ArchivedSessionUser:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier.
          format: uuid
        email:
          type:
          - string
          - 'null'
          description: User email.
        fullName:
          type:
          - string
          - 'null'
          description: User full name.
      additionalProperties: false
      description: Identity of a user attached to an `ArchivedSession`.
    ArchivedSessionEnergyPoint:
      required:
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: Time of the reading.
          format: date-time
        energy:
          type: number
          description: Cumulative energy delivered up to `timestamp`, in kWh.
          format: double
      additionalProperties: false
      description: A single energy reading captured at a point in time during an archived session.
    MaxPhase:
      enum:
      - 1
      - 3
      type: integer
      description: '


        1 = One


        3 = Three'
      format: int32
      x-enumNames:
      - One
      - Three
    SessionEndData:
      type: object
      properties:
        energy:
          type: number
          format: double
        sessionEnd:
          type:
          - string
          - 'null'
          format: date-time
        sessionId:
          type: string
          format: uuid
        sessionStart:
          type: string
          format: date-time
        signedSession:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: 'ISessionEndRequest with optional SessionEnd to allow for both complete and incomplete

        sessions.'
  securitySchemes:
    ory_auth:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.zaptec.com/oauth/token
          scopes: {}