openapi: 3.0.3
info:
  title: HEMS APIs
  description: APIs for Home Energy Management System
  version: 1.0.0
servers:
  - url: https://ems.obeliskapp.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /organization/auth/token:
    post:
      summary: Acquire an access token
      tags:
        - Organization
      description: Acquire an access token for accessing devices and users endpoints
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - organizationId
                - secret
              properties:
                organizationId:
                  format: id
                  type: string
                secret:
                  type: string
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - accessToken
                  - expiresIn
                  - scope
                properties:
                  accessToken:
                    type: string
                  expiresIn:
                    type: number
                  scope:
                    type: array
                    items:
                      anyOf:
                        - type: string
                          enum:
                            - devices:read
                        - type: string
                          enum:
                            - devices:write
                        - type: string
                          enum:
                            - users:read
                        - type: string
                          enum:
                            - users:write
                        - type: string
                          enum:
                            - dashboard:manage
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_BAD_REQUEST
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /users/{userId}/link:
    post:
      summary: Link user device
      tags:
        - User
      description: Link a user device to an organization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - vendor
              properties:
                vendor:
                  description: Vendor of the device
                  type: string
                  enum:
                    - shelly
        required: true
      parameters:
        - schema:
            type: string
          in: path
          name: userId
          required: true
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - callbackUrl
                properties:
                  callbackUrl:
                    type: string
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_BAD_REQUEST
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /users/{userId}/unlink:
    delete:
      summary: Unlink user
      tags:
        - User
      description: Unlink a user and delete all their devices
      parameters:
        - schema:
            type: string
          in: path
          name: userId
          required: true
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_NOT_FOUND
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /users/:
    get:
      summary: List users
      tags:
        - User
      description: List users linked under an organization
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      allOf:
                        - type: object
                          required:
                            - id
                          properties:
                            id:
                              type: string
                        - type: object
                          required:
                            - organizationId
                            - createdAt
                            - updatedAt
                          properties:
                            organizationId:
                              format: id
                              type: string
                            createdAt:
                              format: date-time
                              type: string
                            updatedAt:
                              format: date-time
                              type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /users/{userId}:
    get:
      summary: Get user
      tags:
        - User
      description: Get user details by user id
      parameters:
        - schema:
            type: string
          in: path
          name: userId
          required: true
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - organizationId
                  - createdAt
                  - updatedAt
                  - linkedDevices
                properties:
                  id:
                    type: string
                  organizationId:
                    format: id
                    type: string
                  createdAt:
                    format: date-time
                    type: string
                  updatedAt:
                    format: date-time
                    type: string
                  linkedDevices:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - deviceType
                        - vendor
                      properties:
                        id:
                          format: id
                          type: string
                        deviceType:
                          type: string
                        vendor:
                          description: Vendor of the device
                          type: string
                          enum:
                            - shelly
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_NOT_FOUND
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /users/{userId}/devices:
    get:
      summary: Get user devices
      tags:
        - User
      description: Get user devices by user id
      parameters:
        - schema:
            type: string
          in: path
          name: userId
          required: true
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      allOf:
                        - type: object
                          required:
                            - id
                            - userId
                          properties:
                            id:
                              format: id
                              type: string
                            userId:
                              type: string
                        - type: object
                          required:
                            - vendor
                            - deviceType
                            - deviceCode
                            - accessGroups
                            - name
                            - online
                            - settings
                            - status
                            - createdAt
                            - updatedAt
                          properties:
                            vendor:
                              description: Vendor of the device
                              type: string
                              enum:
                                - shelly
                            deviceType:
                              type: string
                            deviceCode:
                              type: string
                            accessGroups:
                              type: string
                            name:
                              type: array
                              items:
                                type: string
                            online:
                              type: number
                            settings:
                              additionalProperties: true
                              type: object
                              properties: {}
                            status:
                              additionalProperties: true
                              type: object
                              properties: {}
                            createdAt:
                              format: date-time
                              type: string
                            updatedAt:
                              format: date-time
                              type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /devices/:
    get:
      summary: List all devices
      tags:
        - Device
      description: List all devices linked under an organization
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      allOf:
                        - type: object
                          required:
                            - id
                            - userId
                          properties:
                            id:
                              format: id
                              type: string
                            userId:
                              type: string
                        - type: object
                          required:
                            - vendor
                            - deviceType
                            - deviceCode
                            - accessGroups
                            - name
                            - online
                            - settings
                            - status
                            - createdAt
                            - updatedAt
                          properties:
                            vendor:
                              description: Vendor of the device
                              type: string
                              enum:
                                - shelly
                            deviceType:
                              type: string
                            deviceCode:
                              type: string
                            accessGroups:
                              type: string
                            name:
                              type: array
                              items:
                                type: string
                            online:
                              type: number
                            settings:
                              additionalProperties: true
                              type: object
                              properties: {}
                            status:
                              additionalProperties: true
                              type: object
                              properties: {}
                            createdAt:
                              format: date-time
                              type: string
                            updatedAt:
                              format: date-time
                              type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
  /devices/{deviceId}:
    get:
      summary: Get a device
      tags:
        - Device
      description: Get device details by ID
      parameters:
        - schema:
            format: id
            type: string
          in: path
          name: deviceId
          required: true
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - id
                      - userId
                    properties:
                      id:
                        format: id
                        type: string
                      userId:
                        type: string
                  - type: object
                    required:
                      - vendor
                      - deviceType
                      - deviceCode
                      - accessGroups
                      - name
                      - online
                      - settings
                      - status
                      - createdAt
                      - updatedAt
                    properties:
                      vendor:
                        description: Vendor of the device
                        type: string
                        enum:
                          - shelly
                      deviceType:
                        type: string
                      deviceCode:
                        type: string
                      accessGroups:
                        type: string
                      name:
                        type: array
                        items:
                          type: string
                      online:
                        type: number
                      settings:
                        additionalProperties: true
                        type: object
                        properties: {}
                      status:
                        additionalProperties: true
                        type: object
                        properties: {}
                      createdAt:
                        format: date-time
                        type: string
                      updatedAt:
                        format: date-time
                        type: string
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_UNAUTHORIZED
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_NOT_FOUND
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - ERR_INTERNAL_SERVER_ERROR
                  - type: object
                    required:
                      - message
                    properties:
                      message:
                        type: string
                      details: {}
                      stack: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
