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"
  
  /file/upload:
    get:
      tags:
        - File
      summary: Check upload chunk
      parameters:
        - name: path
          in: query
          description: File path
          required: true
          example: "/DATA/test.log"
          schema:
            type: string
        - name: relativePath
          in: query
          description: File path
          required: true
          example: "/DATA/test.log"
          schema:
            type: string
        - name: filename
          in: query
          description: File name
          required: true
          example: "test.log"
          schema:
            type: string
        - name: chunkNumber
          in: query
          description: chunk number
          required: true
          example: 1
          schema:
            type: string
        - name: totalChunks
          in: query
          description: total chunks
          example: 2
          required: true
          schema:
            type: integer
      description: Check if the file block has been uploaded (needs to be modified later)
      operationId: checkUploadChunk
      responses:
        "200":
          $ref: "#/components/responses/ResponseStringOK"
        "400":
          $ref: "#/components/responses/ResponseClientError"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
    post:
      tags:
        - File
      summary: Upload file
      description: Upload file
      operationId: postUploadFile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                relativePath:
                  type: string
                  example: "/DATA/test.log"
                filename:
                  type: string
                  example: "/DATA/test2.log"
                totalChunks:
                  type: string
                  example: "2"
                chunkNumber:
                  type: string
                  example: "20"
                path:
                  type: string
                  example: "/DATA"
                file:
                  type: string
                  format: binary
                chunkSize:
                  type: string
                  example: "1024"
                currentChunkSize:
                  type: string
                  example: "1024"
                totalSize:
                  type: string
                  example: "1024"
                identifier:
                  type: string
                  example: "test.log"
      responses:
        "200":
          $ref: "#/components/responses/ResponseStringOK"
        "400":
          $ref: "#/components/responses/ResponseClientError"
        "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"

    ResponseStringOK:
      description: OK
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessResponseString"

    ResponseClientError:
      description: Client Error
      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: ""
          
    SuccessResponseString:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - properties:
            data:
              type: string
              description: When the interface returns success, this field is the specific success information

    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"