{
  "openapi": "3.0.1",
  "servers": [
    {
      "url": "https://apis.<domain>"
    }
  ],
  "info": {
    "title": "Connhex Firmware Service",
    "description": "HTTP API for managing firmware versions and releases",
    "version": "1.5.0"
  },
  "paths": {
    "/iot/firmwares": {
      "post": {
        "summary": "Creates new firmware",
        "description": "Creates a new firmware model configuration\n\nRequired Permission:\n\n - Resource: ```core:firmwares```\n\n - Action: ```core:firmwares:create```",
        "tags": ["Firmwares"],
        "requestBody": {
          "$ref": "#/components/requestBodies/CreateFirmwareReq"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/CreateFirmwareRes"
          },
          "400": {
            "description": "Failed due to malformed JSON"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to create firmware"
          },
          "409": {
            "description": "Firmware with provided ID already exists"
          },
          "415": {
            "description": "Missing or invalid content type"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    },
    "/iot/firmwares/{firmwareId}": {
      "get": {
        "summary": "Gets firmware info",
        "description": "Retrieves firmware configuration by ID\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:get```",
        "tags": ["Firmwares"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FirmwareRes"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to access firmware"
          },
          "404": {
            "description": "Firmware not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      },
      "put": {
        "summary": "Updates firmware info",
        "description": "Updates firmware configuration\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:update```",
        "tags": ["Firmwares"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/UpdateFirmwareReq"
        },
        "responses": {
          "200": {
            "description": "Firmware updated"
          },
          "400": {
            "description": "Failed due to malformed request"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to update firmware"
          },
          "404": {
            "description": "Firmware not found"
          },
          "415": {
            "description": "Missing or invalid content type"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      },
      "delete": {
        "summary": "Removes firmware",
        "description": "Deletes firmware configuration and all its releases\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:delete```",
        "tags": ["Firmwares"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          }
        ],
        "responses": {
          "204": {
            "description": "Firmware removed"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to delete firmware"
          },
          "404": {
            "description": "Firmware not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    },
    "/iot/firmwares/{firmwareId}/releases": {
      "get": {
        "summary": "Lists firmware releases",
        "description": "Gets all releases for a firmware with pagination\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:listReleases```",
        "tags": ["Releases"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          },
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ReleasesPageRes"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to access firmware"
          },
          "404": {
            "description": "Firmware not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      },
      "post": {
        "summary": "Creates new release",
        "description": "Creates a new firmware release version\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:createRelease```",
        "tags": ["Releases"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/CreateReleaseReq"
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/ReleaseRes"
          },
          "400": {
            "description": "Failed due to malformed request"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to create release"
          },
          "404": {
            "description": "Firmware not found"
          },
          "415": {
            "description": "Missing or invalid content type"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    },
    "/iot/firmwares/{firmwareId}/releases/{releaseId}": {
      "delete": {
        "summary": "Removes release",
        "description": "Deletes a firmware release version\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:deleteRelease```",
        "tags": ["Releases"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          },
          {
            "$ref": "#/components/parameters/ReleaseId"
          }
        ],
        "responses": {
          "204": {
            "description": "Release removed"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to delete release"
          },
          "404": {
            "description": "Firmware or release not found"
          },
          "422": {
            "description": "Cannot remove active release"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    },
    "/iot/firmwares/{firmwareId}/releases/{releaseId}/activate": {
      "post": {
        "summary": "Activates release",
        "description": "Sets a release version as the active version\n\nRequired Permission:\n\n - Resource: ```core:firmwares:{id}```\n\n - Action: ```core:firmwares:activateRelease```",
        "tags": ["Releases"],
        "parameters": [
          {
            "$ref": "#/components/parameters/FirmwareId"
          },
          {
            "$ref": "#/components/parameters/ReleaseId"
          }
        ],
        "responses": {
          "204": {
            "description": "Release activated"
          },
          "401": {
            "description": "Missing or invalid access token provided"
          },
          "403": {
            "description": "User not authorized to activate release"
          },
          "404": {
            "description": "Firmware or release not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    },
    "/iot/ota/{initId}": {
      "get": {
        "summary": "Gets firmware file",
        "description": "Downloads firmware binary file for OTA updates",
        "tags": ["OTA"],
        "security": [
          {
            "thingKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InitId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/FirmwareFileRes"
          },
          "401": {
            "description": "Missing or invalid thing key provided"
          },
          "404": {
            "description": "Firmware not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      },
      "head": {
        "summary": "Gets firmware file metadata",
        "description": "Gets firmware file metadata for OTA updates",
        "tags": ["OTA"],
        "security": [
          {
            "thingKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InitId"
          }
        ],
        "responses": {
          "200": {
            "description": "Firmware file metadata",
            "headers": {
              "Content-Length": {
                "schema": {
                  "type": "integer"
                }
              },
              "Content-Type": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Disposition": {
                "schema": {
                  "type": "string"
                }
              },
              "Content-Digest": {
                "schema": {
                  "type": "string"
                }
              },
              "Version": {
                "schema": {
                  "type": "string"
                }
              },
              "Min-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "Max-Version": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid thing key provided"
          },
          "404": {
            "description": "Firmware not found"
          },
          "500": {
            "$ref": "#/components/responses/ServiceError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Firmware": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique firmware identifier"
          },
          "name": {
            "type": "string",
            "description": "Firmware name",
            "maxLength": 1024
          },
          "architecture": {
            "type": "string",
            "description": "Hardware architecture"
          },
          "description": {
            "type": "string",
            "description": "Description"
          },
          "metadata": {
            "type": "object",
            "description": "Custom metadata"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tags"
          },
          "active_release": {
            "type": "string",
            "description": "Currently active release version"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_by": {
            "type": "string",
            "description": "ID of user who last updated"
          }
        }
      },
      "Release": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique release identifier"
          },
          "version": {
            "type": "string",
            "description": "Version number"
          },
          "note": {
            "type": "string",
            "description": "Release notes"
          },
          "mandatory": {
            "type": "boolean",
            "description": "Whether update is mandatory"
          },
          "min_version": {
            "type": "string",
            "description": "Minimum version that can update to this"
          },
          "max_version": {
            "type": "string",
            "description": "Maximum version that can update to this"
          },
          "filename": {
            "type": "string",
            "description": "Original firmware file name"
          },
          "size": {
            "type": "integer",
            "description": "File size in bytes"
          },
          "checksum": {
            "type": "string",
            "description": "File checksum"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_by": {
            "type": "string",
            "description": "ID of user who last updated"
          }
        }
      },
      "ReleasesPage": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items"
          },
          "offset": {
            "type": "integer",
            "description": "Number of items to skip"
          },
          "limit": {
            "type": "integer",
            "description": "Maximum items per page"
          },
          "releases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Release"
            }
          }
        }
      }
    },
    "parameters": {
      "FirmwareId": {
        "name": "firmwareId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Firmware identifier"
      },
      "ReleaseId": {
        "name": "releaseId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Release identifier"
      },
      "InitId": {
        "name": "initId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Device initialization ID"
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 0,
          "minimum": 0
        },
        "description": "Number of items to skip"
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 10,
          "maximum": 100,
          "minimum": 1
        },
        "description": "Maximum items per page"
      }
    },
    "requestBodies": {
      "CreateFirmwareReq": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["model_id", "name", "architecture"],
              "properties": {
                "model_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string",
                  "maxLength": 1024
                },
                "architecture": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "metadata": {
                  "type": "object"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "UpdateFirmwareReq": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "maxLength": 1024
                },
                "description": {
                  "type": "string"
                },
                "architecture": {
                  "type": "string"
                },
                "metadata": {
                  "type": "object"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "CreateReleaseReq": {
        "required": true,
        "content": {
          "multipart/form-data": {
            "schema": {
              "type": "object",
              "required": ["version", "filename", "bin"],
              "properties": {
                "version": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                },
                "mandatory": {
                  "type": "boolean",
                  "default": false
                },
                "min_version": {
                  "type": "string"
                },
                "max_version": {
                  "type": "string"
                },
                "filename": {
                  "type": "string"
                },
                "bin": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "CreateFirmwareRes": {
        "description": "Firmware created",
        "headers": {
          "Location": {
            "schema": {
              "type": "string",
              "description": "URL of created firmware"
            }
          }
        }
      },
      "FirmwareRes": {
        "description": "Firmware details",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Firmware"
            }
          }
        }
      },
      "ReleasesPageRes": {
        "description": "Page of releases",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ReleasesPage"
            }
          }
        }
      },
      "ReleaseRes": {
        "description": "Release details",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Release"
            }
          }
        }
      },
      "FirmwareFileRes": {
        "description": "Firmware binary file",
        "content": {
          "application/octet-stream": {
            "schema": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "ServiceError": {
        "description": "Unexpected server-side error occurred"
      }
    },
    "securitySchemes": {
      "$ref": "../../../common.json#/components/securitySchemes"
    }
  },
  "security": [{ "chx_auth_session": [] }, { "bearer": [] }]
}