evcc (self-hosted) Db API

openapi: 3.2.0
info:
  title: evcc Db API
  description: smart charging. open source energy management.
  version: 0.2.0
  contact:
    url: https://github.com/evcc-io/evcc
servers:
- url: https://demo.evcc.io/api
tags:
- name: db
paths:
  /db/backup:
    get:
      operationId: downloadBackup
      summary: Download database backup
      description: Downloads the SQLite database as a backup file. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
      - db
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/adminPassword'
      responses:
        '200':
          description: SQLite database file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/restore:
    post:
      operationId: restoreBackup
      summary: Restore database backup
      description: Restores the database from a previously downloaded backup file. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt. The instance restarts after a successful restore.
      tags:
      - db
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/adminPassword'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: SQLite database backup file
      responses:
        '204':
          description: Restore successful, instance is restarting
        '400':
          description: Invalid file or missing fields
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/reset:
    post:
      operationId: resetDatabase
      summary: Reset database
      description: Selectively deletes sessions, settings and/or remote access data from the database. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt. The instance restarts after a successful reset.
      tags:
      - db
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/adminPassword'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessions:
                  type: boolean
                  description: Delete all charging sessions
                settings:
                  type: boolean
                  description: Delete all settings, configs, and meters
                remote:
                  type: boolean
                  description: Delete remote access configuration and registered clients
      responses:
        '204':
          description: Reset successful, instance is restarting
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/metrics/energy:
    delete:
      operationId: deleteEnergyMetrics
      summary: Delete energy metrics
      description: Deletes recorded energy slots in the given time range, optionally narrowed by entity. Filter parameters match /history/energy, so the same request can be previewed there before deleting. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
      - db
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/adminPassword'
      - name: from
        in: query
        required: true
        description: Start time, inclusive (RFC3339)
        schema:
          type: string
          format: date-time
          example: '2026-07-01T00:00:00Z'
      - name: to
        in: query
        required: true
        description: End time, exclusive (RFC3339)
        schema:
          type: string
          format: date-time
          example: '2026-07-02T00:00:00Z'
      - name: group
        in: query
        description: Filter by entity group
        schema:
          type: string
          example: forecast
          enum:
          - forecast
          - battery
          - grid
          - pv
          - home
          - loadpoint
          - meter
          - consumer
          - temperature
      - name: name
        in: query
        description: Filter by entity name
        schema:
          type: string
          example: db:8
      - name: title
        in: query
        description: Filter by entity title
        schema:
          type: string
          example: Battery
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          description: Invalid parameters or database offline
        '401':
          $ref: '#/components/responses/Unauthorized'
  /db/metrics/tariffs:
    delete:
      operationId: deleteTariffMetrics
      summary: Delete tariff metrics
      description: Deletes recorded tariff values in the given time range. Without usage the entire record is removed, otherwise only that usage is cleared and records left without any value are removed. Session users must supply the admin password in the X-Admin-Password header. API key holders via Bearer token are exempt.
      tags:
      - db
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/adminPassword'
      - name: from
        in: query
        required: true
        description: Start time, inclusive (RFC3339)
        schema:
          type: string
          format: date-time
          example: '2026-07-01T00:00:00Z'
      - name: to
        in: query
        required: true
        description: End time, exclusive (RFC3339)
        schema:
          type: string
          format: date-time
          example: '2026-07-02T00:00:00Z'
      - name: usage
        in: query
        description: Limit deletion to a single tariff usage
        schema:
          type: string
          example: co2
          enum:
          - grid
          - feedin
          - co2
          - temperature
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
        '400':
          description: Invalid parameters or database offline
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Password:
      description: Admin password
      type: string
  responses:
    Deleted:
      description: Success - number of deleted records
      content:
        application/json:
          schema:
            type: object
            properties:
              deleted:
                type: integer
                example: 96
    Unauthorized:
      description: Unauthorized - Login and try again
      content:
        text/plain:
          schema:
            type: string
            enum:
            - Unauthorized
  parameters:
    adminPassword:
      name: X-Admin-Password
      in: header
      description: Admin password (required for session auth, not needed for API key)
      schema:
        $ref: '#/components/schemas/Password'
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: auth
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Long-lived API key (prefixed `evcc_`, managed via /auth/apikey).

        Grants access to /api/db/* without requiring the X-Admin-Password header.

        '