openapi: 3.0.0
info:
  description: |
    This is a public API documenting the endpoints available for consumers to retrieve site data to the sites they have access to.


    ## Authentication

    All requests to the Solar Analytics server must include a valid token retrieved using HTTP Basic authentication through user login.

    ## Rate Limits

    Rate limits for the API will be assigned to the user account provided by Solar Analytics. The default limits for API usage is 150/minute and 7200/hour. If the limit is reached with your account the HTTP status code returned will be 429 (Too Many Requests). If you want to increase these limits, please reach out to **support@solaranalytics.com** and we will consider the application.

  version: "2023-06-06"
  title: "SolA Public API Documentation"
  contact:
    email: "support@solaranalytics.com"

servers:
  - url: 'https://portal.solaranalytics.com.au'
    description: Production server for API requests
  - url: 'https://staging-api.solaranalytics.com'
    description: Testing server for API requests. Uptime is not guaranteed.

tags:
  - name: Authentication
    description: API for authenticating to SA services
  - name: Site List
    description: Retrieve summary information for all sites
  - name: Site Data and Status
    description: Retrieve monitoring and site status data

paths:
  /api/v3/token:
    $ref: "./sainternal/V3/paths/token.yaml#/TokenV3"

  /api/v3/site_list:
    $ref: "./sainternal/V3/paths/site_lists.yaml#/FullSiteList"

  /api/v2/site_data/{site_id}:
    $ref: "./sainternal/V2/paths/site_data.yaml"

  /api/v3/live_data:
    $ref: "./sainternal/V3/paths/live_metrology.yaml#/LiveMetrologyData"

  /api/v3/live_site_data:
    $ref: "./sainternal/V3/paths/live_metrology.yaml#/LiveSiteMetrologyData"

  /api/v3/site_status/{site_id}:
    $ref: "./sainternal/V3/paths/faults_endpoints.yaml#/SiteStatus"

  /api/v5/device/data:
    $ref: "./sainternal/V5/paths/device_endpoints.yaml#/DeviceData"
  /api/v5/device/{device_serial}/data:
    $ref: "./sainternal/V5/paths/device_endpoints.yaml#/DeviceSerialData"

components:

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: A valid username and password that has access to SolA dashboard
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The API token retrieved after a successful request is used for all
        following usage of the SA services.

security:
  - bearerAuth: []
