openapi: 3.0.0 info: version: 1.0.0 title: Biotz Developer API description: >- Specification for Biotz's Developer API contact: name: Biotz Academy url: https://academy.biotz.io/ servers: - url: https://api.biotz.io components: securitySchemes: openIdConnect: type: oauth2 x-tokenName: id_token flows: password: tokenUrl: https://auth.biotz.io/realms/biotz-platform/protocol/openid-connect/token scopes: openid: OpenID Connect responses: BadRequest: description: >- The request does not conform to the endpoint specification. content: application/json: schema: type: object properties: reason: type: string example: - "bad-parameter-type-or-format" error-details: type: "object" required: - reason Unauthorized: description: >- The request lacks valid authentication credentials. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-id-token-claims" - "invalid-or-missing-id-token" required: - reason Forbidden: description: >- Operation forbidden. content: application/json: schema: type: object properties: reason: type: string enum: - "no-permission" required: - reason GenericSuccess: description: >- Operation succeeded. content: application/json: schema: type: object GenericError: description: >- The backend could not perform the request, for the reason stated in the response body. content: application/json: schema: type: object properties: reason: type: string example: bad-parameter-type-or-format error-details: description: A map with additional error details. type: object required: - reason GenericNotFound: description: >- The requested entity does not exist. content: application/json: schema: type: object parameters: PaginationPage: name: "pagination[page]" in: query schema: $ref: "#/components/schemas/PaginationPage" PaginationPageSize: name: "pagination[page-size]" in: query schema: $ref: "#/components/schemas/PaginationPageSize" FilterSearch: name: "filters[search]" in: query schema: type: string schemas: AnyValue: description: >- Can be anything: string, number, array, object, etc. (except `null`) PaginationPage: type: integer default: 0 minimum: 0 PaginationPageSize: type: integer maximum: 50 default: 10 PaginationResponse: type: object required: - page - page-size - total-count properties: page: $ref: "#/components/schemas/PaginationPage" page-size: $ref: "#/components/schemas/PaginationPageSize" total-count: type: integer minimum: 0 example: 1 DeviceType: type: object required: - id - org-id - display-name - name - created-at properties: id: type: string format: uuid org-id: type: string format: uuid display-name: type: string minLength: 1 name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 maxLength: 20 description: type: string nullable: true created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true DeviceTypeForCreate: type: object required: - name - display-name - org-id properties: name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 maxLength: 20 display-name: type: string minLength: 1 description: type: string nullable: true org-id: type: string format: uuid DeviceTypeForUpdate: type: object properties: display-name: type: string minLength: 1 description: type: string nullable: true CommunicationProtocol: type: string enum: - "http" - "mqtt" PayloadSerializationFormat: type: string enum: - "json" - "message-pack" DataIngestionMessageType: type: object required: - id - device-type-id - name - data-table-name - communication-protocol - payload-serialization-format - created-at properties: id: type: string format: uuid device-type-id: type: string format: uuid display-name: type: string minLength: 1 description: type: string minLength: 1 nullable: true name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 maxLength: 12 data-table-name: type: string pattern: "^data_[a-z0-9_]+$" minLength: 8 maxLength: 63 data-model-metadata: type: array items: $ref: "#/components/schemas/AnyValue" nullable: true communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true DataIngestionMessageTypeForCreate: type: object required: - device-type-id - display-name - name - communication-protocol - payload-serialization-format properties: device-type-id: type: string format: uuid display-name: type: string minLength: 1 name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 maxLength: 12 description: type: string minLength: 1 nullable: true communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" DataIngestionMessageTypeForUpdate: type: object properties: display-name: type: string minLength: 1 description: type: string minLength: 1 nullable: true DataIngestionMessageTypeSchema: type: object required: - id - name - message-type-id - defintion - created-at properties: id: type: string format: uuid name: type: string minLength: 1 message-type-id: type: string format: uuid definition: type: object created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true DataIngestionMessageTypeSchemaForCreate: type: object properties: name: type: string minLength: 1 message-type-id: type: string format: uuid definition: type: object ActionMessageType: type: object required: - id - device-type-id - display-name - name - communication-protocol - payload-serialization-format - created-at properties: id: type: string format: uuid device-type-id: type: string format: uuid display-name: type: string minLength: 1 description: type: string nullable: true minLength: 1 name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true ActionMessageTypeForCreate: type: object required: - device-type-id - display-name - name - communication-protocol - payload-serialization-format properties: device-type-id: type: string format: uuid display-name: type: string minLength: 1 description: type: string nullable: true minLength: 1 name: type: string pattern: "^[a-z_][a-z0-9_]+$" minLength: 1 communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" ActionMessageTypeForUpdate: type: object properties: display-name: type: string minLength: 1 description: type: string nullable: true minLength: 1 ActionMessageTypeSchema: type: object required: - id - name - action-message-type-id - definition - created-at properties: id: type: string format: uuid name: type: string minLength: 1 action-message-type-id: type: string format: uuid definition: type: object created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true ActionMessageTypeSchemaForCreate: type: object required: - name - action-message-type-id - definition properties: name: type: string minLength: 1 action-message-type-id: type: string format: uuid definition: type: object AlarmLevel: type: string enum: - emergency - critical - alert - warning - info AlarmRule: type: array items: $ref: "#/components/schemas/AnyValue" example: "[]" Alarm: type: object required: - id - device-id - alarm-triggering-data-timestamp - triggered-at - level - trigger properties: id: type: string format: uuid device-id: type: string format: uuid alarm-triggering-data-timestamp: type: string format: date-time triggered-at: type: string format: date-time nullable: true level: type: string enum: - emergency - critical - alert - warning - info trigger: type: object properties: id: type: string format: uuid display-name: type: string rule: $ref: "#/components/schemas/AlarmRule" AlarmTrigger: type: object required: - id - display-name - message-type-id - level - rule properties: id: type: string format: uuid display-name: type: string minLength: 1 message-type-id: type: string format: uuid level: $ref: "#/components/schemas/AlarmLevel" rule: $ref: "#/components/schemas/AlarmRule" device-ids: type: array items: type: string format: uuid notification-user-ids: type: array items: type: string format: uuid AlarmTriggerForCreate: type: object required: - display-name - message-type-id - level - rule properties: display-name: type: string minLength: 1 message-type-id: type: string format: uuid level: $ref: "#/components/schemas/AlarmLevel" rule: $ref: "#/components/schemas/AlarmRule" notification-user-ids: type: array items: type: string AlarmTriggerForUpdate: type: object required: - display-name - message-type-id - level - rule properties: display-name: type: string minLength: 1 message-type-id: type: string format: uuid level: $ref: "#/components/schemas/AlarmLevel" rule: $ref: "#/components/schemas/AlarmRule" notification-user-ids: type: array items: type: string format: uuid Tag: type: object required: - id - tag-key - tag-value - created-at properties: id: type: string format: uuid tag-key: type: string minLength: 1 tag-value: type: string minLength: 1 created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true TagForAssignation: type: object required: - tag-key - tag-value properties: id: type: string format: uuid tag-key: type: string minLength: 1 tag-value: type: string minLength: 1 BomStandard: type: string enum: - cyclonedx-1-3-json - cyclonedx-1-4-json - cyclonedx-1-5-json - cyclonedx-1-3-xml - cyclonedx-1-4-xml - cyclonedx-1-5-xml Firmware: type: object required: - id - device-type-id - content-file-id - name - version - created-at properties: id: type: string format: uuid device-type-id: type: string format: uuid content-file-id: type: string format: uuid name: type: string minLength: 1 version: type: string minLength: 1 description: type: string nullable: true tags: type: array items: $ref: "#/components/schemas/Tag" created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true FirmwareForCreate: type: object required: - device-type-id - name - content-file properties: device-type-id: type: string format: uuid name: type: string minLength: 1 version: type: string minLength: 1 description: type: string nullable: true content-file: type: string format: binary sbom-standard: $ref: "#/components/schemas/BomStandard" sbom-file-content: type: string format: binary tags: type: array items: $ref: "#/components/schemas/TagForAssignation" FirmwareForUpdate: type: object properties: description: type: string nullable: true sbom-standard: $ref: "#/components/schemas/BomStandard" sbom-file-content: type: string format: binary tags: type: array items: $ref: "#/components/schemas/TagForAssignation" Timezone: type: string example: "Europe/Madrid" Device: type: object required: - id - device-type-id - name - created-at - last-updated-at properties: id: type: string format: uuid device-type-id: type: string format: uuid name: type: string minLength: 1 description: type: string minLength: 1 nullable: true timezone: $ref: "#/components/schemas/Timezone" nullable: true tags: type: array items: $ref: "#/components/schemas/Tag" created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true DeviceForCreate: type: object required: - device-type-id - name properties: device-type-id: type: string format: uuid name: type: string minLength: 1 description: type: string minLength: 1 nullable: true timezone: $ref: "#/components/schemas/Timezone" nullable: true tags: type: array items: $ref: "#/components/schemas/TagForAssignation" DeviceForUpdate: type: object properties: name: type: string minLength: 1 description: type: string minLength: 1 nullable: true timezone: $ref: "#/components/schemas/Timezone" nullable: true tags: type: array items: $ref: "#/components/schemas/TagForAssignation" DeviceCreationResult: type: object required: - id - password - mqtt-username - http-username - customer-id properties: id: type: string format: uuid password: type: string mqtt-username: type: string http-username: type: string customer-id: type: string format: uuid DeviceCredentials: type: object required: - http-username - mqtt-username - password - customer-id properties: http-username: type: string mqtt-username: type: string password: type: string customer-id: type: string format: uuid JobType: type: string enum: - export-device-data JobStatus: type: string enum: - created - running - completed - failed Job: type: object required: - id - type - status - parameters - created-at properties: id: type: string format: uuid type: $ref: '#/components/schemas/JobType' status: $ref: '#/components/schemas/JobStatus' parameters: type: object result: type: object created-at: type: string format: date-time started-at: type: string format: date-time ended-at: type: string format: date-time DataAggregationMethod: type: string enum: - count - max - min - sum - mean - stddev - first - last DeviceEventTopicSuffix: description: >- Topic suffix used to send this kind of device type event. The actual topic name must use a prefix hard-coded by the platform, followed by this suffix. allOf: - type: string minLength: 1 maxLength: 512 - type: string pattern: "^[^\\./]+|[^\\./][^\\.]+[^\\./]$" example: network/status DeviceEvent: type: object properties: id: type: string format: uuid device-type-id: description: >- Id of the device type for which to create the event. type: string format: uuid display-name: description: >- Name to display for the device type event. type: string minLength: 1 topic-suffix: $ref: "#/components/schemas/DeviceEventTopicSuffix" communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" notification-webhook-ids: description: >- Array of webhooks ids, used to notify external systems about the reception of this kind of device events. type: array items: type: string format: uuid created-at: type: string format: date-time last-updated-at: type: string format: date-time nullable: true required: - id - device-type-id - display-name - topic-suffix - communication-protocol - payload-serialization-format - created-at DeviceEventForCreate: type: object properties: device-type-id: description: >- Id of the device type for which to create the event. type: string format: uuid display-name: description: >- Name to show for the device type event. type: string minLength: 1 topic-suffix: $ref: "#/components/schemas/DeviceEventTopicSuffix" communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" notification-webhook-ids: type: array items: type: string format: uuid required: - device-type-id - display-name - topic-suffix - communication-protocol - payload-serialization-format DeviceEventForUpdate: type: object properties: display-name: description: >- Name to show for the device type event. type: string minLength: 1 topic-suffix: description: >- Topic suffix used to send this kind of device type event. The actual topic name must use a prefix hard-coded by the platform, followed by this suffix. allOf: - type: string minLength: 1 maxLength: 512 - type: string pattern: ^[^\\./]+|[^\\./][^\\.]+[^\\./]$ example: network/status communication-protocol: $ref: "#/components/schemas/CommunicationProtocol" payload-serialization-format: $ref: "#/components/schemas/PayloadSerializationFormat" notification-webhook-ids: type: array items: type: string format: uuid required: - display-name - topic-suffix - communication-protocol - payload-serialization-format security: - openIdConnect: - openid paths: /device-type: post: tags: ["device-type"] description: >- Create a new device-type. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceTypeForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "name-already-exists" '500': $ref: '#/components/responses/GenericError' /device-type/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["device-type"] description: >- Update the device-type for the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceTypeForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' get: tags: ["device-type"] description: >- Get the device-type for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: device-type: $ref: '#/components/schemas/DeviceType' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["device-type"] description: >- Delete the device-type identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /device-types/by-org/{org-id}: parameters: - name: org-id in: path required: true schema: type: string format: uuid get: tags: ["device-type"] description: >- Get the list of device-types for a given organization. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "display-name_asc" - "display-name_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/DeviceType' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /data-ingestion/message-type: post: tags: ["data-ingestion-message-type"] description: >- Create a Data Ingestion Message Type. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DataIngestionMessageTypeForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "name-already-exists" '500': $ref: '#/components/responses/GenericError' /data-ingestion/message-type/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["data-ingestion-message-type"] description: >- Update the Data Ingestion Message Type for the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DataIngestionMessageTypeForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' get: tags: ["data-ingestion-message-type"] description: >- Get the Data Ingestion Message Type for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: data-ingestion-msg-type: $ref: '#/components/schemas/DataIngestionMessageType' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["data-ingestion-message-type"] description: >- Delete the Data Ingestion Message Type identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /data-ingestion/message-types/by-device-type/{device-type-id}: parameters: - name: device-type-id in: path required: true schema: type: string format: uuid get: tags: ["data-ingestion-message-type"] description: >- Get the list of Data Ingestion Message Types for a given Device Type. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "display-name_asc" - "display-name_desc" - "communication-protocol_asc" - "communication-protocol_desc" - "payload-serialization-format_asc" - "payload-serialization-format_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/DataIngestionMessageType' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /data-ingestion/message-type-schema: post: tags: ["data-ingestion-message-type-schema"] description: >- Create a Data Ingestion Message Type Schema. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DataIngestionMessageTypeSchemaForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "not-compatible-schema" '500': $ref: '#/components/responses/GenericError' /data-ingestion/message-type-schema/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["data-ingestion-message-type-schema"] description: >- Get the Data Ingestion Message Type Schema for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: data-ingestion-msg-type-schema: $ref: '#/components/schemas/DataIngestionMessageTypeSchema' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["data-ingestion-message-type-schema"] description: >- Delete the Data Ingestion Message Type Schema identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /message-type-schemas/by-message-type/{message-type-id}: parameters: - name: message-type-id in: path required: true schema: type: string format: uuid get: tags: ["data-ingestion-message-type-schema"] description: >- Get the list of Data Ingestion Message Type Schemas for a given Device Type, identified by its id. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/DataIngestionMessageTypeSchema' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /action/message-type: post: tags: ["action-message-type"] description: >- Create an Action Message Type. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ActionMessageTypeForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "name-already-exists" '500': $ref: '#/components/responses/GenericError' /action/message-type/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["action-message-type"] description: >- Update the Action Message Type for the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ActionMessageTypeForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' get: tags: ["action-message-type"] description: >- Get the Action Message Type for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" required: - action-msg-type properties: action-msg-type: $ref: '#/components/schemas/ActionMessageType' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["action-message-type"] description: >- Delete the Action Message Type identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /action/message-types/by-device-type/{device-type-id}: parameters: - name: device-type-id in: path required: true schema: type: string format: uuid get: tags: ["action-message-type"] description: >- Get the list of Action Message Types for a given Device Type. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "display-name_asc" - "display-name_desc" - "communication-protocol_asc" - "communication-protocol_desc" - "payload-serialization-format_asc" - "payload-serialization-format_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/ActionMessageType' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /action/message-type-schema: post: tags: ["action-message-type-schema"] description: >- Create an Action Message Type Schema. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ActionMessageTypeSchemaForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /action/message-type-schema/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["action-message-type-schema"] description: >- Get the Action Message Type Schema for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: action-msg-type-schema: $ref: '#/components/schemas/ActionMessageTypeSchema' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["action-message-type-schema"] description: >- Delete the Data Ingestion Message Type Schema identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /action/message-type-schemas/by-message-type/{message-type-id}: parameters: - name: message-type-id in: path required: true schema: type: string format: uuid get: tags: ["action-message-type-schema"] description: >- Get the list of Action Message Type Schemas for a given Device Type. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/ActionMessageTypeSchema' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /action/publish: post: tags: ["action-publish"] description: >- Publish an action to a list of devices. requestBody: required: true content: multipart/form-data: schema: type: object required: - action-message-type-schema-id - devices-ids - payload-file properties: action-message-type-schema-id: type: string format: uuid devices-ids: type: array items: type: string format: uuid payload-file: type: string format: binary responses: '200': $ref: '#/components/responses/GenericSuccess' '400': description: >- The request does not conform to the endpoint specification. content: application/json: schema: type: object required: - reason properties: reason: type: string enum: - "bad-parameter-type-or-format" - "invalid-payload-format" error-details: type: "object" '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /alarms/by-org/{org-id}: parameters: - name: org-id in: path required: true schema: type: string format: uuid get: tags: ["alarm"] description: >- Get the list of Alarms for a given Organization. parameters: - name: "filters[device-id]" in: query required: false schema: type: string format: uuid - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "triggered-at_desc" enum: - "triggered-at_asc" - "triggered-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/Alarm' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /alarm/trigger: post: tags: ["alarm-trigger"] description: >- Create a new Alarm Trigger. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AlarmTriggerForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /alarm/trigger/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["alarm-trigger"] description: >- Update an Alarm Trigger for the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AlarmTriggerForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' get: tags: ["alarm-trigger"] description: >- Get the Alarm Trigger for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" required: - alarm-trigger properties: alarm-trigger: $ref: '#/components/schemas/AlarmTrigger' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["alarm-trigger"] description: >- Delete the Alarm Trigger identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /alarm/triggers/by-device-type/{device-type-id}: parameters: - name: device-type-id in: path required: true schema: type: string format: uuid get: tags: ["alarm-trigger"] description: >- Get the list of Alarm Triggers for a given Device Type. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "display-name_asc" - "display-name_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/AlarmTrigger' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /firmware: post: tags: ["firmware"] description: >- Create a Firmware. requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/FirmwareForCreate" encoding: tags: contentType: application/json responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "name-already-exists" - "invalid-sbom" '500': $ref: '#/components/responses/GenericError' /firmware/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["firmware"] description: >- Get the Firmware for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: firmware: $ref: '#/components/schemas/Firmware' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["firmware"] description: >- Delete the Firmware identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' put: tags: ["firmware"] description: >- Update the Firmware identified by the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/FirmwareForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-sbom" - "resend-defintion-to-change-sbom-standard" '500': $ref: '#/components/responses/GenericError' /firmware/{id}/content-file: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["firmware"] responses: '200': description: >- Request performed successfully. content: application/octet-stream: schema: type: string format: byte '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /firmware/{id}/sbom-file-url: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["firmware"] responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: file-url: type: string format: uri '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /firmwares/by-device-type/{device-type-id}: parameters: - name: device-type-id in: path required: true schema: type: string format: uuid get: tags: ["firmware"] description: >- Get the list of Firmwares for a given Device Type. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/Firmware' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /device: post: tags: ["device"] description: >- Create a Device. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: $ref: '#/components/schemas/DeviceCreationResult' text/csv: schema: type: string format: byte '400': description: >- The request does not conform to the endpoint specification. content: application/json: schema: type: object properties: reason: type: string enum: - "bad-parameter-type-or-format" - "invalid-tags" error-details: type: "object" required: - reason '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string enum: - "name-already-exists" '500': $ref: '#/components/responses/GenericError' '512': description: >- Partial error. content: application/json: schema: type: object properties: reason: type: string enum: - "could-not-encode-csv" result: $ref: '#/components/schemas/DeviceCreationResult' /device/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["device"] description: >- Update the Device identified by the given id. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceForUpdate" responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' get: tags: ["device"] description: >- Get the Device for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: device: $ref: '#/components/schemas/Device' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' delete: tags: ["device"] description: >- Delete the Device identified by the given id. responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /device/{id}/reset-credentials: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["device"] description: >- Reset the credentials for the Device with the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: credentials: $ref: '#/components/schemas/DeviceCredentials' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /devices/by-org/{org-id}: parameters: - name: org-id in: path required: true schema: type: string format: uuid get: tags: ["device"] description: >- Get the Devices for a given Organization. parameters: - $ref: '#/components/parameters/FilterSearch' - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: device-type-id in: query schema: type: string format: uuid - name: timezone in: query schema: $ref: '#/components/schemas/Timezone' - name: sort-by in: query schema: type: string default: "name_asc" enum: - "name_asc" - "name_desc" - "timezone_asc" - "timezone_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/Device' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /devices/request-firmware-update: post: tags: ["device"] description: >- Send a firmware update request to a list of devices. requestBody: required: true content: application/json: schema: type: object required: - device-ids - firmware-id properties: device-ids: type: array items: type: string format: uuid firmware-id: type: string format: uuid responses: '200': $ref: '#/components/responses/GenericSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /data-ingestion/query/last-value: get: tags: ["data-ingestion-query"] description: >- Given a Message Type identified by its id (`message-type-id` parameter), get the last **non-empty** (non-null) data values sent by the Device identified by its id (`device-id` parameter), for the attribute names listed in the `attribute-names` parameter. Notice that if the Device has sent recent messages of the given Message Type with one or more of those values missing, or set to `NULL`, this endpoint will ignore those more recent messages and will return the value(s) from the most recent message where they were not missing or were not `NULL`. parameters: - name: message-type-id in: query required: true schema: type: string format: uuid - name: device-id in: query required: true schema: type: string format: uuid - name: attribute-names in: query required: true schema: type: array minItems: 1 maxItems: 25 items: type: string responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - last-value-data properties: last-value-data: type: object required: - timestamp properties: attribute_name_1: type: object required: - timestamp - value properties: timestamp: type: string format: date-time value: type: string attribute_name_2: type: object required: - timestamp - value properties: timestamp: type: string format: date-time value: type: boolean attribute_name_n: type: object required: - timestamp - value properties: timestamp: type: string format: date-time value: type: integer '400': description: >- Bad request. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-attribute-names" - "bad-parameter-type-or-format" error-details: type: "object" required: - reason '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /data-ingestion/query/last-message-value: get: tags: ["data-ingestion-query"] description: >- Given a Message Type identified by its id (`message-type-id` parameter), get the data values of the **last message** of that type sent by the Device identified by its id (`device-id` parameter), for the attribute names listed in the `attribute-names` parameter. Notice that this endpoint will always return the values from the last message of the given Message Type, irrespective of whether the values were missing in the message, in which case they will be returned as `NULL`, or were `NULL`. parameters: - name: message-type-id in: query required: true schema: type: string format: uuid - name: device-id in: query required: true schema: type: string format: uuid - name: attribute-names in: query required: true schema: type: array minItems: 1 maxItems: 25 items: type: string responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - last-message-value-data properties: last-message-value-data: type: object required: - timestamp properties: timestamp: type: string format: date-time attribute_name_1: type: string attribute_name_2: type: boolean attribute_name_n: type: integer '400': description: >- Bad request. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-attribute-names" - "bad-parameter-type-or-format" error-details: type: "object" required: - reason '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /data-ingestion/query/time-series: get: tags: ["data-ingestion-query"] description: >- Given a Message Type identified by its id (`message-type-id` parameter), get the time-series data belonging to the Device identified by the `device-id` parameter, for the attribute names listed in the `attribute-names` parameter, in the time interval starting at `time-range[from]` and ending at `time-range[end]`. At most `max-data-points` values will be returned. The values will be computed from the raw data sent by the Device, by aggregating the raw values according to the `aggregration-method` parameter. parameters: - name: message-type-id in: query required: true schema: type: string format: uuid - name: device-id in: query required: true schema: type: string format: uuid - name: attribute-names in: query required: true schema: type: array minItems: 1 maxItems: 25 items: type: string - name: aggregation-method in: query required: true schema: $ref: '#/components/schemas/DataAggregationMethod' - name: max-data-points in: query required: true schema: type: integer minimum: 1 maximum: 4000 - name: time-range[from] in: query required: true schema: type: string format: date-time - name: time-range[to] in: query required: true schema: type: string format: date-time responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - time-series-data properties: time-series-data: type: object example: '{ "attribute_1": [ [ "2023-09-22T09:08:20.915170823", 1 ], [ "2023-09-22T09:08:21.615170823", 3 ] ], "attribute_2": [ [ "2023-09-22T09:08:20.915170823", 1.5 ], [ "2023-09-22T09:08:21.615170823", 4.2 ] ] }' '400': description: >- Bad request. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-attribute-names" - "bad-parameter-type-or-format" error-details: type: "object" required: - reason '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /data-ingestion/export: post: tags: ["data-ingestion-export"] description: >- Export the raw data of a given Device and Message type. requestBody: required: true content: application/json: schema: type: object required: - filters - attribute-names properties: filters: required: - device-id - message-type-id - time-range properties: device-id: type: string format: uuid message-type-id: type: string format: uuid time-range: type: object properties: from: type: string format: date-time to: type: string format: date-time attribute-names: type: array items: type: string responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - last-value-data properties: job: $ref: '#/components/schemas/Job' '400': description: >- Bad request. content: application/json: schema: type: object properties: reason: type: string enum: - "invalid-attribute-names" - "bad-parameter-type-or-format" error-details: type: "object" required: - reason '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /job/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["job"] description: >- Get the Job for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: "object" properties: job: $ref: '#/components/schemas/Job' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /jobs/by-org/{org-id}: parameters: - name: org-id in: path required: true schema: type: string format: uuid get: tags: ["job"] description: >- Get the Job for a given Organization. parameters: - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - name: filters[type] in: query schema: $ref: '#/components/schemas/JobType' - name: filters[status] in: query schema: $ref: '#/components/schemas/JobStatus' - name: sort-by in: query schema: type: string default: "created-at_asc" enum: - "created-at_asc" - "created-at_desc" - "started-at_asc" - "started-at_desc" - "ended-at_asc" - "ended-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/Job' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/GenericError' /developer-tools/webhook: post: tags: ["webhook"] summary: "Create a new webhook" description: "Create a new webhook for a specified organization." requestBody: required: true content: application/json: schema: type: object properties: name: type: string url: type: string org-id: type: string format: uuid responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: id: type: string format: uuid '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /developer-tools/webhook/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["webhook"] summary: "Get webhook by id" description: "Retrieve a webhook by its ID." responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string format: uuid name: type: string url: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' put: tags: ["webhook"] summary: "Update a webhook" description: "Update the details of a webhook." requestBody: required: true content: application/json: schema: type: object properties: name: type: string url: type: string responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' delete: tags: ["webhook"] summary: "Delete webhook by id" description: "Delete a webhook by its ID." responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' /developer-tools/webhook/{id}/rotate-secret: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["webhook"] summary: "Rotate webhook secret" description: "Rotate the secret for a webhook." responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /developer-tools/webhook/{id}/status: parameters: - name: id in: path required: true schema: type: string format: uuid put: tags: ["webhook"] summary: "Set webhook status" description: "Set the status of a webhook." requestBody: required: true content: application/json: schema: type: object properties: status: type: string responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /developer-tools/webhooks/by-org/{org-id}: get: tags: ["webhook"] summary: "Get all webhooks" description: "Retrieve all webhooks for a specified organization." parameters: - name: org-id in: path required: true schema: type: string format: uuid responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: type: string format: uuid name: type: string url: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /device-event: post: tags: ["device-event"] description: >- Create new a device event. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceEventForCreate" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: id: description: >- The id of the newly created device event. type: string format: uuid required: - id '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string required: - reason '500': $ref: '#/components/responses/GenericError' /device-event/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: ["device-event"] description: >- Get the details of a device event for the given id. responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object properties: device-event: $ref: "#/components/schemas/DeviceEvent" required: - device-event '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' put: tags: ["device-event"] description: >- Update a device event. parameters: - in: path name: id required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/DeviceEventForUpdate" type: object responses: '200': $ref: "#/components/responses/GenericSuccess" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '409': description: >- The backend cannot perform the request because there is conflict with another resource of the same type. content: application/json: schema: type: object properties: reason: type: string required: - reason '500': $ref: '#/components/responses/GenericError' delete: tags: ["device-event"] description: >- Delete a device event. responses: '200': $ref: "#/components/responses/GenericSuccess" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError' /device-events/by-device-type/{device-type-id}: parameters: - in: path name: device-type-id required: true schema: type: string format: uuid get: tags: ["device-event"] description: >- Get the list of device events for a given device type. parameters: - in: query name: "filters[search]" description: >- Retrieve only the device events whose display name or topic suffix matches the search string. required: false schema: type: string - $ref: '#/components/parameters/PaginationPage' - $ref: '#/components/parameters/PaginationPageSize' - in: query name: sort-by description: >- How to sort the returned list of device events. schema: default: "display-name_asc" enum: - "display-name_asc" - "display-name_desc" - "event-topic-suffix_asc" - "event-topic-suffix_desc" - "communication-protocol_asc" - "communication-protocol_desc" - "payload-serialization-format_asc" - "payload-serialization-format_desc" - "created-at_asc" - "created-at_desc" - "last-updated-at_asc" - "last-updated-at_desc" responses: '200': description: >- Request performed successfully. content: application/json: schema: type: object required: - list - pagination properties: list: type: array items: $ref: '#/components/schemas/DeviceEvent' pagination: $ref: '#/components/schemas/PaginationResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/GenericNotFound' '500': $ref: '#/components/responses/GenericError'