CasaOS/api/casaos/openapi.yaml

openapi: 3.0.3

info:
  title: CasaOS API
  version: v2
  description: |
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_dark_night_800px.png">
        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_twilight_blue_800px.png">
        <img alt="CasaOS" src="https://raw.githubusercontent.com/IceWhaleTech/logo/main/casaos/casaos_banner_twilight_blue_800px.png">
    </picture>

    CasaOS API provides miscellaneous methods for different scenarios.

    For issues and discussions, please visit the [GitHub repository](https://github.com/IceWhaleTech/CasaOS) or join [our Discord](https://discord.gg/knqAbbBbeX).    

servers:
  - url: /v2/casaos

tags:
  - name: Health methods
    description: |-
       These methods are used to check the health and status of the CasaOS API and associated services.        

  - name: File methods 
    description: |-
      The File methods allow you to interact with files and directories on the CasaOS system.      

x-tagGroups:
  - name: Methods
    tags:
      - Health methods

security:
  - access_token: []

paths:
  /health/services:
    get:
      tags:
        - Health methods
      summary: Get service status
      description: |-
        Get running status of each `casaos-*` service.        
      operationId: getHealthServices
      responses:
        "200":
          $ref: "#/components/responses/GetHealthServicesOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"

  /health/ports:
    get:
      tags:
        - Health methods
      summary: Get port in use
      operationId: getHealthPorts
      responses:
        "200":
          $ref: "#/components/responses/GetHealthPortsOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
  /health/logs:
    get:
      tags:
        - Health methods
      summary: Get log
      operationId: getHealthlogs
      responses:
        "200":
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"

  /file/test:
    get:
      tags:
        - File methods
      summary: Test file methods
      description: |-
        Test file methods.        
      operationId: getFileTest
      responses:
        "200":
          $ref: "#/components/responses/ResponseOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
  /zt/info:
    get:
      tags:
        - Zerotier methods
      summary: Get Zerotier info
      description: |-
        Get Zerotier info.        
      operationId: getZerotierInfo
      responses:
        "200":
          $ref: "#/components/responses/GetZTInfoOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
  /zt/{network_id}/status:
    put:  
      tags:
        - Zerotier methods
      summary: Set Zerotier network status
      description: |-
        Set Zerotier network status.        
      operationId: setZerotierNetworkStatus
      parameters:
        - name: network_id
          in: path
          description: network id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  enum:
                    - online
                    - offline
                  type: string
                  example: "online"
      responses:
        "200":
          $ref: "#/components/responses/GetZTInfoOK"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"

components:
  securitySchemes:
    access_token:
      type: apiKey
      in: header
      name: Authorization

  responses:
    ResponseOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    ResponseInternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BaseResponse"

    GetHealthServicesOK:
      description: OK
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/BaseResponse"
              - properties:
                  data:
                    $ref: "#/components/schemas/HealthServices"

    GetHealthPortsOK:
      description: OK
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/BaseResponse"
              - properties:
                  data:
                    $ref: "#/components/schemas/HealthPorts"
    GetZTInfoOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ZTInfo"


  schemas:
    BaseResponse:
      properties:
        message:
          readOnly: true
          description: message returned by server side if there is any
          type: string
          example: ""

    HealthServices:
      properties:
        running:
          type: array
          items:
            type: string
            example: "casaos-gateway.service"
        not_running:
          type: array
          items:
            type: string
            example: "casaos.service"

    HealthPorts:
      properties:
        tcp:
          type: array
          items:
            type: integer
            example: 80
          x-go-name: TCP
        udp:
          type: array
          items:
            type: integer
            example: 53
          x-go-name: UDP
    ZTInfo:
      properties:
        id:
          type: string
          example: "1234567890"
        name:
          type: string
          example: "CasaOS"
        status:
          type: string
          example: "online"