openapi: 3.0.3
info:
  title: Reposit Customer API - OpenAPI 3.0
  description: |-
    
    This is an informal description of external Reposit API provided to Reposit
    customers.

    All questions, feedback, feature requests, etc. should be directed to
    <api@repositpower.com>.

    Homepage: <https://api.repositpower.com/>
    
    Authentication types
    ====================
    
    There are two options for authentication, Stateless authentication and API authentication
    
    Stateless authentication
    ---------
    To do stateless authentication you need to send the header `Reposit-Auth: Stateless` when you first login on the 
    `/v2/auth/login/` route and also for every subsequent request. The `access_token` that you receive should be sent 
    in every subsequent request as a header in the format `Authorization: Bearer <access_token>` This access token 
    expires, with the expiry given to you when you first receive the access token, so you will need to reauthenticate 
    afterwards.
    
    API authentication
    ---
    To do stateful authentication you need to send the header `Reposit-Auth: API` when you first login on the 
    `/v2/auth/login/` route and also for every subsequent request. The login response will also include a 
    `refresh_token` that you can use to refresh your access token before it expires. To do this you need to make a 
    request to the `/v2/auth/refresh` route (see below).  
    Like in stateless authentication, the `access_token` that you receive should be sent in every subsequent request 
    as a header in the format `Authorization: Bearer <access_token>`.

  contact:
    email: api@repositpower.com
  version: 2023.5.1
servers:
  - url: https://api.repositpower.com/
tags:
  - name: auth
    description: Authentication operations
  - name: deployment
    description: Deployment operations
paths:
  /v2/auth/login/:
    post:
      tags:
        - auth
      summary: Login route
      description: Log into your account and receive an authentication token
      parameters:
        - $ref: '#/components/parameters/repositAuthHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /v2/auth/refresh/:
    post:
      tags:
        - auth
      summary: Auth token refresh route
      description: Post your refresh token to this route when using API auth in order to get a new token
      parameters:
        - $ref: '#/components/parameters/repositAuthHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
        required: true
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshResponse'
  /v2/userkeys/:
    get:
      tags:
        - auth
      summary: This endpoint returns all userkeys/battery system identifiers for the current user
      parameters:
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserKeys'

  /v2/deployments/{userkey}/components:
    get:
      tags:
        - deployment
      summary: Get a list of components of your deployment (the Reposit Box and attached hardware)
      parameters:
        - $ref: '#/components/parameters/userkeyParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentsResponse'

  /v2/deployments/{userkey}/battery/capacity:
    get:
      tags:
        - deployment
        - battery
      summary: Get the current capacity of the battery (or batteries) of the given deployment
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatteryCapacity'

  /v2/deployments/{userkey}/generation/historical/p:
    get:
      tags:
        - deployment
        - solar
      summary: Get solar generation data as negative real_power in kW
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationHistoricalP'
  /v2/deployments/{userkey}/inverter/historical/p:
    get:
      tags:
        - deployment
        - inverter
        - solar
      summary: Get battery inverter data as real_power in kW
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InverterHistoricalP'
  /v2/deployments/{userkey}/house/historical:
    get:
      tags:
        - deployment
      summary: Get house consumption in kW
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HouseHistorical'
  /v2/deployments/{userkey}/battery/historical/soc:
    get:
      tags:
        - deployment
      summary: Get state of charge of a battery in kWh
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatteryHistoricalSoC'
  /v2/deployments/{userkey}/meter/historical/p:
    get:
      tags:
        - deployment
      summary: Get real power measurements in kW at the grid connection
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeterHistoricalP'
  /v2/deployments/{userkey}/gridcredits/historical:
    get:
      tags:
        - deployment
      summary: Get earned GridCredits in $
      parameters:
        - $ref: "#/components/parameters/userkeyParam"
        - $ref: '#/components/parameters/startParam'
        - $ref: '#/components/parameters/endParam'
        - $ref: '#/components/parameters/deltaTParam'
        - $ref: '#/components/parameters/repositAuthHeader'
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridCreditsHistorical'
components:
  schemas:
    LoginRequest:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
    LoginResponse:
      type: object
      properties:
        access_token:
          type: string
        expires_at:
          type: integer
    RefreshRequest:
      type: object
      properties:
        refresh_token:
          type: string
    RefreshResponse:
      type: object
      properties:
        access_token:
          type: string
    UserKeys:
      type: object
      properties:
        userKeys:
          type: array
          items:
            type: string

    ComponentsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            ac_dc:
              type: boolean
            battery:
              type: boolean
            dc_coupled:
              type: boolean
            frequency_trigger:
              type: boolean
            inverter:
              type: boolean
            load_meter:
              type: boolean
            load_phases:
              type: array
              items:
                type: string
            solar_meter:
              type: boolean
            solar_phases:
              type: array
              items:
                type: string
            solar_streams_ac:
              $ref: '#/components/schemas/StreamComponent'
            solar_streams_dc:
              $ref: '#/components/schemas/StreamComponent'

    StreamComponent:
      type: object
      properties:
        <uid>:
          type: object
          properties:
            name:
              type: string
            phases:
              type: object
              properties:
                <phase>:
                  type: string
    BatteryCapacity:
      type: object
      properties:
        batteryCapacity:
          description: Battery capacity from 0.0 to 1.0 (0% to 100%)
          type: number
    GenerationHistoricalP:
      type: object
      properties:
        solarP:
          type: array
          items:
            type: array
            items:
              type: number

    InverterHistoricalP:
      type: object
      properties:
        inverterP:
          type: array
          items:
            type: array
            items:
              type: number
    HouseHistorical:
      type: object
      properties:
        data:
          type: object
          properties:
            components:
              $ref: '#/components/schemas/ComponentsResponse'
            houseP:
              type: array
              items:
                type: array
                items:
                  type: number

    BatteryHistoricalSoC:
      type: object
      properties:
        batteryCapacity:
          type: number
        batterySOC:
          type: array
          items:
            type: array
            items:
              type: number

    MeterHistoricalP:
      type: object
      properties:
        meterP:
          type: array
          items:
            type: array
            items:
              type: number

    CostHistorical:
      type: object
      properties:
        retailCost:
          type: array
          items:
            type: array
            items:
              type: number

    GridCreditsHistorical:
      type: object
      properties:
        gridcredits:
          type: array
          items:
            type: array
            items:
              type: number
  parameters:
    repositAuthHeader:
      name: Reposit-Auth
      in: header
      description: The kind of authentication used (API or Stateless)
      schema:
        type: string
        default: 'Stateless'
    userkeyParam:
      name: userkey
      in: path
      description: The userkey of the deployment to get data for
      required: true
      schema:
        type: string
    startParam:
      name: start
      in: query
      description: The start UNIX timestamp
      required: false
      schema:
        type: integer
    endParam:
      name: end
      in: query
      description: The end UNIX timestamp
      required: false
      schema:
        type: integer
    deltaTParam:
      name: delta_t
      in: query
      description: The number of seconds between each data point
      required: false
      schema:
        type: integer
        default: 300
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT