openapi: 3.2.0
info:
  title: Braiins OS Public REST License API
  description: ''
  contact:
    name: Braiins
    url: https://help.braiins.com
    email: help@braiins.com
  license:
    name: ''
  version: 1.7.0
servers:
- url: http://miner/
tags:
- name: License
paths:
  /api/v1/license/apply-contract-key:
    put:
      tags:
      - License
      summary: Apply custom contract key
      description: Apply custom contract key. An already installed license is replaced by the new one unless `keep_existing` is set to `true`. Bosminer is not restarted automatically; when `successful` is `true`, restart bosminer for the new license to take effect.
      operationId: applyContractKey
      requestBody:
        description: Custom contract key to be set.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyContractKeyRequest'
        required: true
      responses:
        '200':
          description: Successful response with successful flag to indicate success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyContractKeyResponse'
  /api/v1/license/license:
    get:
      tags:
      - License
      summary: Get license state
      description: 'Retrieves the current license state of the miner. The license may be in one of several states: none, limited, valid, or expired.'
      operationId: getLicenseState
      responses:
        '200':
          description: Successful response containing information about license
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLicenseStateResponse'
components:
  schemas:
    State:
      oneOf:
      - type: object
        required:
        - none
        properties:
          none:
            $ref: '#/components/schemas/NoneLicense'
      - type: object
        required:
        - limited
        properties:
          limited:
            $ref: '#/components/schemas/LimitedLicense'
      - type: object
        required:
        - valid
        properties:
          valid:
            $ref: '#/components/schemas/ValidLicense'
      - type: object
        required:
        - expired
        properties:
          expired:
            $ref: '#/components/schemas/ExpiredLicense'
    LimitedLicense:
      type: object
    BasesPoints:
      type: object
      description: Structure representing Basis Points
      required:
      - bsp
      properties:
        bsp:
          type: integer
          format: int32
          description: 'A basis point is one hundredth of 1 percentage point.

            For example: 1bps = 0.01%, 250bps = 2.5%'
          minimum: 0
    ExpiredLicense:
      type: object
      required:
      - type
      - contract_name
      properties:
        contract_name:
          type: string
          description: Contract name
        dev_fee:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BasesPoints'
            description: Defines how much DevFee should be generated by the device.
        type:
          type: integer
          format: int32
          description: License type
    GetLicenseStateResponse:
      type: object
      properties:
        state:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/State'
    ApplyContractKeyResponse:
      type: object
      required:
      - successful
      properties:
        successful:
          type: boolean
          description: 'Flag if custom license was successfully installed. It is `true` when the new license was

            downloaded and installed, both when no contract key was applied before and when a previously

            installed license was overwritten. It is `false` when `keep_existing` was set and an already

            installed license was kept untouched regardless of its current state, so the new key was not

            applied. Any failure to download or install the new license is reported as an error instead;

            when an existing license was being overwritten, it may already have been removed at that point

            and is not restored.'
    ValidLicense:
      type: object
      required:
      - type
      - contract_name
      - time_to_restricted
      properties:
        contract_name:
          type: string
          description: Contract name
        dev_fee:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BasesPoints'
            description: Defines how much DevFee should be generated by the device.
        time_to_restricted:
          type: integer
          format: int32
          description: 'Current license expiration - number of seconds since the moment the license was received

            i.e., number of seconds BOS will start mining in restricted mode burning 15% of hashrate'
          minimum: 0
        type:
          type: integer
          format: int32
          description: License type
    ApplyContractKeyRequest:
      type: object
      required:
      - contract_key
      properties:
        contract_key:
          type: string
          description: Licence contract key string
        keep_existing:
          type:
          - boolean
          - 'null'
          description: 'Flag if an already installed license should be kept. When set to true, an already installed

            license is kept untouched and the new contract key is not applied. When set to false or

            omitted, the license is overwritten by the new contract key. The flag is ignored when no

            contract key was applied before; the new contract key is always applied in that case.'
    NoneLicense:
      type: object
      required:
      - time_to_restricted
      properties:
        time_to_restricted:
          type: integer
          format: int32
          description: 'BOS Initialization timeout - number of seconds elapsed since bosminer start

            i.e., number of seconds BOS will start mining in restricted mode burning 5% of hashrate

            For more, see Section 3.10 of <https://braiins.com/os/plus/license>'
          minimum: 0