ev.energy Charging Sessions API

openapi: 3.2.0
info:
  title: ev.energy v2 Charging Sessions API
  version: '2.0'
  contact:
    email: developers@ev.energy
    url: developers.ev.energy
    name: ev.energy developers
  description: The official API for ev.energy, version 2.
  license:
    name: Proprietary
    url: https://ev.energy
  termsOfService: ''
servers:
- url: https://api.ev.energy/v2
  description: Live API for both production and sandbox requests.
  x-internal: false
- description: Staging server for internal testing only.
  url: https://api-staging.ev.energy/v2
  x-internal: true
security:
- oauth2: []
tags:
- name: Charging Sessions
  description: Endpoints related to records of charging. See [Understanding charging data](docs/understanding/charging_sessions.md) for how charging sessions (plug-in episodes), charging sub-sessions (per-mode segments) and energy usage intervals (actual energy delivery) relate to each other.
paths:
  /charging_sessions:
    get:
      summary: List charging sessions
      description: 'List all charging sessions visible to the authenticated client. Each session represents one physical plug-in episode: its start/end are the plug-in and unplug times. A session contains one or more charging sub-sessions — one per contiguous period in a single charging mode.


        Charging sessions are recorded from the feature''s release (July 2026) onwards; earlier charging history is not backfilled and is available only as charging sub-sessions.


        See [Understanding charging data](docs/understanding/charging_sessions.md) for how charging sessions, sub-sessions and energy usage intervals relate.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns a list of charging sessions, sorted newest first.
          headers:
            Link:
              $ref: '#/components/headers/link'
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargingSession'
        '400':
          $ref: '#/components/responses/Problem400BadRequestList'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sessions
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/previous'
      - $ref: '#/components/parameters/next'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/expand-on-chargingsession'
      - $ref: '#/components/parameters/user'
      security:
      - oauth2:
        - charging_session:read
  /charging_sessions/{charging_session_id}:
    parameters:
    - $ref: '#/components/parameters/charging_session_id'
    get:
      summary: Retrieve a charging session
      description: 'Retrieve a specific charging session representing one physical plug-in episode: its start/end are the plug-in and unplug times. See [Understanding charging data](docs/understanding/charging_sessions.md).'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns a single charging session.
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSession'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sessions-charging_session_id
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsession'
      - $ref: '#/components/parameters/user'
      security:
      - oauth2:
        - charging_session:read
  /charging_sessions/{charging_session_id}/boost_start:
    parameters:
    - $ref: '#/components/parameters/charging_session_id'
    post:
      summary: Start boost charging
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Boost charging was started. Returns the charging session resource.
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSession'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '409':
          $ref: '#/components/responses/Problem409Conflict'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
        '503':
          $ref: '#/components/responses/Problem503ServiceUnavailable'
      operationId: post-charging_sessions-charging_session_id-boost_start
      description: 'Start boost charging on this charging session''s vehicle. Finishes the

        in-progress smart charging sub-session and starts a replacement boost

        sub-session, charging the vehicle continuously rather than around the

        cheapest/greenest times. The plug-in episode (this resource) continues

        unchanged.


        Returns `409 Conflict` if smart charging is turned off for the

        vehicle, or if this session''s current sub-session is not an

        in-progress smart charging session that can be boosted.'
      security:
      - oauth2:
        - charging_session:write
  /charging_sessions/{charging_session_id}/boost_end:
    parameters:
    - $ref: '#/components/parameters/charging_session_id'
    post:
      summary: End boost charging
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Boost charging was ended. Returns the charging session resource.
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSession'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '409':
          $ref: '#/components/responses/Problem409Conflict'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
        '503':
          $ref: '#/components/responses/Problem503ServiceUnavailable'
      operationId: post-charging_sessions-charging_session_id-boost_end
      description: 'End boost charging on this charging session''s vehicle. Finishes the

        in-progress boost sub-session and starts a replacement smart charging

        sub-session, returning the vehicle to charging around the

        cheapest/greenest times. The plug-in episode (this resource) continues

        unchanged.


        Returns `409 Conflict` if smart charging is turned off for the

        vehicle, or if this session''s current sub-session is not currently

        boosting.'
      security:
      - oauth2:
        - charging_session:write
  /charging_sub_sessions:
    get:
      summary: List charging sub sessions
      description: 'List all charging sub sessions visible to the authenticated client.


        A charging sub-session is a segment of a plug-in episode during which a single charging mode (SMART, BOOST, etc.) was active. Its start/end mark when that mode started and stopped being active — they are not plug-in/plug-out times (see the charging_sessions resource for those), and they are not the times energy was actually flowing (see the sub-session''s energy_usage endpoint for those).


        See [Understanding charging data](docs/understanding/charging_sessions.md) for how charging sessions, sub-sessions and energy usage intervals relate.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns a list of charging sub sessions, sorted newest first.
          headers:
            Link:
              $ref: '#/components/headers/link'
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChargingSubSession'
        '400':
          $ref: '#/components/responses/Problem400BadRequestList'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/previous'
      - $ref: '#/components/parameters/next'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/expand-on-chargingsubsession'
      - $ref: '#/components/parameters/evse_id_q'
      - $ref: '#/components/parameters/vehicle_id_q'
      - $ref: '#/components/parameters/user_id_q'
      - $ref: '#/components/parameters/user'
      - $ref: '#/components/parameters/energy_delivered_watt_hours__gte'
      - $ref: '#/components/parameters/energy_delivered_watt_hours__lte'
      - $ref: '#/components/parameters/is_finished'
      - $ref: '#/components/parameters/mode'
      - schema:
          type: string
          format: date-time
        in: query
        name: start__gt
        description: Only return sessions that started after the passed date
      - schema:
          type: string
          format: date-time
        in: query
        name: start__lt
        description: Only return sessions that started before the passed date
      - schema:
          type: string
          format: date-time
        in: query
        name: end__gt
        description: Only return sessions that ended after the passed date
      - schema:
          type: string
          format: date-time
        in: query
        name: end__lt
        description: Only return sessions that ended before the passed date
      security:
      - oauth2:
        - charging_session:read
  /charging_sub_sessions/{charging_sub_session_id}:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve a charging sub-session
      description: Retrieve a specific charging sub-session, representing a period of a plug-in episode during which a single charging mode was active. Its start/end mark when the mode started and stopped being active — not plug-in/plug-out times, and not when energy was actually flowing. See [Understanding charging data](docs/understanding/charging_sessions.md).
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns information about a single charging sub-session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSubSession'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession'
      security:
      - oauth2:
        - charging_session:read
  /charging_sub_sessions/{charging_sub_session_id}/energy_usage:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve periodic energy usage intervals for a charging sub-session
      description: 'Retrieve periodic energy usage intervals for a specific charging sub-session. This is the endpoint to use to find out when energy was actually delivered to the vehicle.


        A sub-session''s start/end only mark when its charging mode was active — within that window, energy delivery may begin late (e.g. smart charging waiting for an off-peak period), finish early (e.g. the target charge level was reached), or occur in several separate bursts. The intervals returned here report the actual delivery.


        By default, intervals are regular fixed-length periods. If you are looking for intervals that cover the whole time energy is being delivered (which are therefore of irregular length) — for example to find the actual charging windows — use the `merge_consecutive_intervals` query parameter. Gaps where no energy flowed are returned as intervals with zero energy delivered; filter them out with `energy_delivered_watt_hours__gt=0` if you only want the charging windows.


        See [Understanding charging data](docs/understanding/charging_sessions.md) for how charging sessions, sub-sessions and energy usage intervals relate.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns information about a single charging sub-session's energy usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyUsage'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-energy_usage
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-energyusage'
      - $ref: '#/components/parameters/energy_delivered_watt_hours__gt'
      - schema:
          type: boolean
        in: query
        name: merge_consecutive_intervals
        description: 'Request consecutive intervals of energy delivery (and intervals of no delivery) to be merged into combined periods of irregular length. '
      security:
      - oauth2:
        - charging_session:read
  /charging_sub_sessions/{charging_sub_session_id}/flags:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve flags for a charging sub-session
      description: 'Retrieve flags associated with a specific charging sub-session.


        Flags highlight particular types of issues or anomalies detected during a charging session, along with their root causes.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns the flags associated with this charging sub-session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSubSessionFlags'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-flags
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-flags'
      security:
      - oauth2:
        - charging_session:read
  /charging_sub_sessions/{charging_sub_session_id}/debug_metadata:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve debug metadata for a charging sub-session
      description: 'Retrieve debug metadata for a specific charging sub-session.


        Debug metadata exposes session-level diagnostic information such as start/finish reasons, the energy usage calculation and interpolation methods used, whether energy delivery was capped, and the solar integration type of the paired EVSE.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns the debug metadata associated with this charging sub-session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSubSessionDebugMetadata'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-debug_metadata
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-debug-metadata'
      security:
      - oauth2:
        - debug:read
  /charging_sub_sessions/{charging_sub_session_id}/schedules:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve schedules for a charging sub-session
      description: 'Retrieve schedules for a specific charging sub-session.


        Schedules represent charging instructions for a charging session. Each schedule specifies a current (in milliamps) and a time period during which that current should be applied.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns information about a single charging sub-session's schedules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedules'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-schedules
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-schedules'
      - schema:
          type: string
          format: date-time
        in: query
        name: started_at__gte
        description: Filter schedules with started_at greater than or equal to this datetime.
      - schema:
          type: string
          format: date-time
        in: query
        name: started_at__lte
        description: Filter schedules with started_at less than or equal to this datetime.
      - schema:
          type: string
          pattern: scpl[A-Z\d]{26}
          example: scpl01HSH04KDEWF6Z4DB2J77J74K5
        in: query
        name: schedule_plan_id
        description: Filter schedules generated from a specific schedule plan.
      - schema:
          type: boolean
          default: true
        in: query
        required: false
        name: only_most_recently_created
        description: Only show the most recently created schedule for each time period
      security:
      - oauth2:
        - chargingsession:read
  /charging_sub_sessions/{charging_sub_session_id}/schedule_plans:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve schedule plans for a charging sub-session
      description: 'Retrieve schedule plans for a specific charging sub-session.


        Schedule plans represent the charging plan parameters used to generate schedules for a charging session. Each plan contains information about the ready-by time, charging requirements, and constraints that were used to create the charging schedule.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns schedule plans for a charging sub-session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulePlans'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-schedule_plans
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-scheduleplans'
      - schema:
          type: string
          format: date-time
        in: query
        name: created_at__gte
        description: Filter schedule plans with created_at greater than or equal to this datetime.
      - schema:
          type: string
          format: date-time
        in: query
        name: created_at__lte
        description: Filter schedule plans with created_at less than or equal to this datetime.
      security:
      - oauth2:
        - debug:read
  /charging_sub_sessions/{charging_sub_session_id}/assessment:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    get:
      summary: Retrieve assessment for a charging sub-session
      description: 'Retrieve the performance assessment for a specific charging sub-session.


        The assessment contains performance metrics for completed charging sessions, including energy delivery ratios, charge rates, and detailed quality metrics.'
      tags:
      - Charging Sessions
      responses:
        '200':
          description: Returns the assessment for a charging sub-session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargingSubSessionAssessment'
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: get-charging_sub_sessions-charging_sub_session_id-assessment
      parameters:
      - $ref: '#/components/parameters/version-2'
      - $ref: '#/components/parameters/expand-on-chargingsubsession-assessment'
      security:
      - oauth2:
        - debug:read
      x-stoplight:
        id: chargingsubsession-assessment-endpoint
  /charging_sub_sessions/{charging_sub_session_id}/recalculate_energy_usages:
    parameters:
    - $ref: '#/components/parameters/charging_sub_session_id'
    post:
      summary: Recalculate energy usages for a charging sub-session
      description: 'Triggers a recalculation of energy usages (and performance assessment) for a completed

        charging sub-session. Use `dry_run` to preview the recalculation without persisting

        changes, and `cap_overages` to control whether energy overages are capped.

        '
      tags:
      - Charging Sessions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                  default: false
                  description: If true, the recalculation is simulated and no changes are persisted.
                cap_overages:
                  type: boolean
                  default: true
                  description: If true, energy overages are capped during recalculation.
      responses:
        '200':
          description: 'Recalculation has been triggered (or simulated if `dry_run` was true). The

            response includes the total energy delivered for the session both before and

            after the recalculation so the caller can see the effect. When `dry_run` is

            true, `new_energy_delivered_watt_hours` reflects the prospective value that

            would result from the recalculation (no persistence).

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - previous_energy_delivered_watt_hours
                - new_energy_delivered_watt_hours
                properties:
                  status:
                    type: string
                    enum:
                    - recalculation_triggered
                    - dry_run_completed
                    example: recalculation_triggered
                  previous_energy_delivered_watt_hours:
                    type: integer
                    description: Total energy delivered for the session before the recalculation, in watt-hours.
                    example: 3500
                  new_energy_delivered_watt_hours:
                    type: integer
                    description: Total energy delivered for the session after the recalculation, in watt-hours. When `dry_run` is true, this is the prospective value that would result from committing.
                    example: 4250
          headers:
            EvEnergy-Version:
              $ref: '#/components/headers/version-2'
            X-RateLimit-Limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            RetryAfter:
              $ref: '#/components/headers/retry-after'
        '400':
          $ref: '#/components/responses/Problem400BadRequestRetrieve'
        '401':
          $ref: '#/components/responses/Problem401Unauthorized'
        '403':
          $ref: '#/components/responses/Problem403Forbidden'
        '404':
          $ref: '#/components/responses/Problem404NotFound'
        '406':
          $ref: '#/components/responses/Problem406NotAcceptable'
        '429':
          $ref: '#/components/responses/Problem429TooManyRequests'
      operationId: post-charging_sub_sessions-charging_sub_session_id-recalculate_energy_usages
      parameters:
      - $ref: '#/components/parameters/version-2'
      security:
      - oauth2:
        - charging_session:write
      x-stoplight:
        id: chargingsubsession-recalculate-energy-usages-endpoint
  /di

# --- truncated at 32 KB (161 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ev-energy/refs/heads/main/openapi/ev-energy-charging-sessions-api-openapi.yml