{"openapi":"3.0.1","info":{"title":"Devices API","version":"v3","description":"Entry point for device provisioning and configuration"},"servers":[{"url":"https://devices.fundamentum-iot.com"}],"components":{"securitySchemes":{"oAuthFundamentum":{"type":"oauth2","description":"See https://oauth.fundamentum-iot.com/oauth-clients for details on oauth integration.","flows":{"implicit":{"authorizationUrl":"https://oauth.fundamentum-iot.com/oauth/authorize","scopes":{}}}},"provisioningKey":{"type":"http","scheme":"bearer"},"deviceJwtKey":{"type":"http","scheme":"bearer"}},"parameters":{"projectId":{"in":"path","name":"project_id","required":true,"description":"Project's ID","schema":{"type":"integer","example":1}},"regionId":{"in":"path","name":"region_id","required":true,"description":"Region's ID","schema":{"type":"integer","example":1,"default":1}},"assetTypeId":{"in":"path","name":"asset_type_id","required":true,"description":"Asset Type's ID","schema":{"type":"integer","example":1,"default":1}},"registryId":{"in":"path","name":"registry_id","required":true,"description":"Registry's ID","schema":{"type":"integer","example":1}},"provisioningKey":{"in":"path","name":"key","required":true,"description":"Provisioning Key","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"}},"serialNumber":{"in":"path","name":"serial_number","required":true,"description":"Device's serial number, which is case insensitive","schema":{"type":"string","example":"sn-123456-no-space"}},"serialNumberStrict":{"in":"path","name":"serial_number","required":true,"description":"Device's serial number which has to be lowercase and contain only alphanumeric characters or hyphens \"-\"","schema":{"type":"string","example":"sn-123-abc"}}},"schemas":{"RegistryIdStrict":{"type":"int","description":"The device's registry ID","example":1},"Date":{"type":"string","description":"A date in the \"yyyy-mm-dd\" format","example":"2024-02-29"},"Status":{"type":"string","description":"The response status which is either \"success\" or \"error\"","example":"success"},"SerialNumber":{"type":"string","description":"The device serial number, which is case insensitive. It must be unique in the registry.","example":"ABC123"},"SerialNumberStrict":{"type":"string","description":"The device's serial number, which is composed of lowercase alphanumeric characters and hyphens \"-\" and underscores \"_\" . It also must be unique in the registry","example":"abc123"},"PublicKey":{"type":"string","description":"Device public key","example":"-----BEGIN PUBLIC KEY-----MIIBIj...AQAB-----END PUBLIC KEY-----"},"Secret":{"type":"string","description":"Device secret. New version of public key","example":"-----BEGIN PUBLIC KEY-----MIIBIj...AQAB-----END PUBLIC KEY-----"},"Algorithm":{"type":"string","description":"Authorization algorithm. The following options are currently supported \"RS256\" and \"Password\"","example":"RS256"},"ProjectId":{"type":"integer","description":"The ID of the project associated with the device.","example":123},"RegistryId":{"type":"integer","description":"The ID of the registry.","example":123},"ErrorResponse":{"properties":{"status":{"$ref":"#/components/schemas/Status"},"message":{"type":"string","description":"The error message"},"data":{"type":"object","description":"More information about the error. This field may be empty depending on error type"}}},"Uptime":{"type":"integer","description":"Time in seconds the device has been up","example":1},"MQTT":{"type":"object","description":"MQTT configuration of the device","properties":{"host":{"type":"string","description":"MQTT Host","example":"mqtt.fundamentum.test"},"port":{"type":"string","description":"MQTT Port","example":1883}}},"ShelfDevice":{"type":"object","description":"Shelf Device's data","properties":{"id":{"type":"integer","description":"Shelf Device's id","example":1},"created_at":{"type":"datetime","description":"Shelf Device's date","example":"2023-06-07T14:31:30.293876Z"},"updated_at":{"type":"datetime","description":"Shelf Device's last update","example":"2023-06-07T14:31:30.293876Z"},"deleted_at":{"type":"datetime","description":"Shelf Device's delete date","example":"2023-06-07T14:31:30.293876Z"},"project_id":{"$ref":"#/components/schemas/ProjectId"},"serial_number":{"$ref":"#/components/schemas/SerialNumberStrict"},"secret":{"$ref":"#/components/schemas/Secret"},"algorithm":{"$ref":"#/components/schemas/Algorithm"}}},"ShelfDeviceRegistryData":{"type":"object","description":"Shelf Device registry connection data","properties":{"registry_id":{"$ref":"#/components/schemas/RegistryId"},"mqtt_host":{"type":"string","description":"Shelf Device's MQTT Hostname","example":"mqtt.fundamentum-iot.com"},"mqtt_port":{"type":"integer","description":"Shelf Device's MQTT Port","example":1883}}},"ShelfDeviceInput":{"type":"object","properties":{"serial_number":{"$ref":"#/components/schemas/SerialNumberStrict"},"secret":{"$ref":"#/components/schemas/Secret"},"algorithm":{"$ref":"#/components/schemas/Algorithm"}}},"ShelfDeviceProvisionInput":{"type":"object","properties":{"registry_id":{"$ref":"#/components/schemas/RegistryIdStrict"}}},"ShelfDeviceProvisionResponse":{"type":"object","properties":{"device_id":{"type":"integer"},"configuration":{"type":"object"},"mqtt":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"client_id":{"type":"string"}}}}},"ProvisioningKey":{"type":"object","description":"Provisioning Key's data","properties":{"id":{"type":"integer","description":"Provisioning Key's id","example":1},"created_at":{"type":"datetime","description":"Provisioning Key's date","example":"2023-06-07T14:31:30.293876Z"},"updated_at":{"type":"datetime","description":"Provisioning Key's last update","example":"2023-06-07T14:31:30.293876Z"},"deleted_at":{"type":"datetime","description":"Provisioning Key's delete date","example":"2023-06-07T14:31:30.293876Z"},"project_id":{"$ref":"#/components/schemas/ProjectId"},"start_at":{"type":"datetime","description":"Provisioning Key's start date","example":"2023-06-07T14:31:30.293876Z"},"end_at":{"type":"datetime","description":"Provisioning Key's end date","example":"2023-09-09T14:31:30.293876Z"},"key":{"type":"string","description":"Provisioning Key's value","example":"edd6dcda-9eb7-477e-82d7-5925eb9a252e"}}},"ProvisioningKeyInput":{"type":"object","properties":{"start_at":{"$ref":"#/components/schemas/Date"},"end_at":{"$ref":"#/components/schemas/Date"}}},"DeviceId":{"type":"integer","description":"Device's id","example":1},"DeviceTypeId":{"type":"integer","description":"Device's type","example":1},"AssetTypeId":{"type":"integer","description":"Device's asset type","example":1},"Configuration":{"type":"object","description":"The settings currently applied on the device.","example":{}},"PendingConfiguration":{"type":"object","description":"A requested configuration change that has not yet been confirmed by the device. The applied configuration only changes once the device confirms it, unless the update was forced.\n","example":{},"nullable":true},"MetaData":{"type":"object","description":"Free-form data attached to the device for reference. Metadata updates take effect immediately.","example":{}},"DeviceResponseContent":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"Device's data","properties":{"device_id":{"$ref":"#/components/schemas/DeviceId"},"device_type_id":{"$ref":"#/components/schemas/DeviceTypeId"},"configuration":{"$ref":"#/components/schemas/Configuration"},"pending_configuration":{"$ref":"#/components/schemas/PendingConfiguration"},"meta_data":{"$ref":"#/components/schemas/MetaData"},"mqtt":{"$ref":"#/components/schemas/MQTT"}}}}}},"responses":{"Error400":{"description":"There is an error with the request's content. For example, a field is missing or has the wrong type.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"error","message":"There is an error with the request","data":{"errors":{"type":"field","msg":"Invalid value","path":"serial_number","location":"body"}}}}}},"Error403":{"description":"The user does not have the permissions to access or edit the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"error","message":"No permission to do this action"}}}},"Error404":{"description":"The resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"error","message":"Resource not found"}}}},"Error409":{"description":"The request encountered a conflict with the state of the target resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"error","message":"Authorization conflict","data":{"error":"device already provisioned"}}}}},"Error422":{"description":"The request tries to do something impossible. For example, it tries to create a resource that is already created.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"status":"error","data":{"serial_number":"The serial number has already been taken"}}}}}}},"paths":{"/status":{"get":{"operationId":"GetServiceStatus","description":"Get service's status","responses":{"200":{"description":"Service is up and running","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"The response status","example":"success"},"data":{"type":"object","description":"The service's status","properties":{"version":{"type":"number","description":"The current service version","example":2},"redis_status":{"type":"string","description":"The status of the redis cache","example":"ready"},"request":{"type":"object","description":"The request's parameters"}}}}}}}}}}},"/api/{version}/swagger.json":{"get":{"operationId":"DownloadSwaggerDocumentation","description":"Downloads the json file containing the swagger documentation of the API","parameters":[{"in":"path","name":"version","description":"The version of the API. Versions 1 to 3 are currently supported","required":true,"schema":{"type":"string","example":"v3"}}],"responses":{"200":{"description":"Success"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}/telemetry":{"post":{"tags":["Telemetry"],"security":[{"deviceJwtKey":[]}],"operationId":"v3-PublishTelemetry","summary":"Publish the telemetry data of a device","description":"Publish the telemetry data of a device to the event bus. The telemetry are data about the sensor's readings.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumber"}],"requestBody":{"description":"The telemetry data of the device. The payload will be forwarded to the event bus.","required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"The telemetry data was published successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}/states":{"get":{"operationId":"v3-GetDeviceStates","summary":"Get the latest states of a device","tags":["States"],"security":[{"oAuthFundamentum":[]}],"parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"Returns the last states of the device","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"The device's latest states"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/asset-types/{asset_type_id}/shelf-devices/{serial_number}":{"get":{"tags":["Shelf Devices"],"security":[{"provisioningKey":[]}],"operationId":"v3-GetShelfDevice","summary":"Get shelf device","description":"Get the shelf device information's. A shelf device registered isn't provisioned until it is assign to a Registry.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The shelf device was found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDevice"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}},"delete":{"tags":["Shelf Devices"],"security":[{"provisioningKey":[]}],"operationId":"v3-DeleteShelfDevice","summary":"Delete a Shelf Device","description":"Delete a Shelf Device\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The shelf device was deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDevice"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/asset-types/{asset_type_id}/shelf-devices":{"post":{"tags":["Shelf Devices"],"security":[{"provisioningKey":[]}],"operationId":"v3-CreateShelfDevice","summary":"Store a Shelf Device","description":"Register a new Shelf Device with the provided serial number and his authentication methods. Device will not be provisioned until it is assigned to a Registry.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"}],"requestBody":{"description":"The shelf device's data","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShelfDeviceInput"}}}},"responses":{"200":{"description":"The shelf device was created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDevice"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/asset-types/{asset_type_id}/shelf-devices/{serial_number}/provision":{"post":{"tags":["Shelf Devices"],"security":[{"provisioningKey":[]}],"operationId":"v3-ProvisionShelfDevice","summary":"Provision a Shelf Device","description":"Provision an existing Shelf Device with the provided registry id.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"requestBody":{"description":"The shelf device's data","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShelfDeviceProvisionInput"}}}},"responses":{"200":{"description":"The shelf device was provisionned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDeviceProvisionResponse"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}},"delete":{"tags":["Shelf Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-DeprovisionShelfDevice","summary":"Deprovision a Shelf Device","description":"Deprovision an provisionned Shelf Device\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The shelf device was deprovisionned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDevice"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/asset-types/{asset_type_id}/shelf-devices/{serial_number}/registry-id":{"get":{"tags":["Shelf Devices"],"security":[{"deviceJwtKey":[]}],"operationId":"v3-GetShelfDeviceRegistryId","summary":"Get shelf device registry id","description":"Get the shelf device information's. A shelf device registered isn't provisioned until it is assign to a Registry.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/assetTypeId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The shelf device was found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ShelfDeviceRegistryData"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}},"/api/v3/registries/{registry_id}/token":{"get":{"tags":["Registries"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-GetToken","summary":"Get registry token","description":"Get the registry's token file values","parameters":[{"$ref":"#/components/parameters/registryId"}],"responses":{"200":{"description":"The token was retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"The response data.","properties":{"server_url":{"type":"string","description":"the server url","example":"devices.fundamentum-iot.com"},"mqtt_host":{"type":"string","description":"the registry`s mqtt host","example":"mqtt.fundamentum-iot.com"},"mqtt_port":{"type":"integer","description":"the registry`s mqtt port","example":8883},"token":{"type":"string","description":"the registry's secret token","example":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9eyJ0ZXN0IjoiMSIsInZhbGlkIjoiMSIsInBhZGRpbmciOiIxIn0"},"project_id":{"type":"integer","description":"The project ID associated with the registry","example":1},"region_id":{"type":"integer","description":"The region ID associated with the registry","example":2},"registry_id":{"type":"integer","description":"The registry's ID","example":3}}}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/provisioning-keys":{"get":{"tags":["Provisioning Keys"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-IndexProvisioningKey","summary":"Get active provisioning keys","description":"Get the active (dates are current) provisioning keys for the project.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"}],"responses":{"200":{"description":"The active provisioning keys","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProvisioningKey"}}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}},"post":{"tags":["Provisioning Keys"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-CreateProvisioningKey","summary":"Create a Provisioning Key","description":"Create a new provisioning key with the provided dates.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"}],"requestBody":{"description":"The provisioning key's data","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisioningKeyInput"}}}},"responses":{"200":{"description":"The provisioning key was created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ProvisioningKey"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/provisioning-keys/{key}":{"get":{"tags":["Provisioning Keys"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-GetProvisioningKey","summary":"Get provisioning key","description":"Get the provisioning key information's.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/provisioningKey"}],"responses":{"200":{"description":"The provisioning key was found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ProvisioningKey"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}},"delete":{"tags":["Provisioning Keys"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-DestroyProvisioningKey","summary":"Destroy a Provisioning Key","description":"Deletes the provisioning key by ID.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/provisioningKey"}],"responses":{"200":{"description":"The provisioning key device was deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"$ref":"#/components/schemas/ProvisioningKey"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/provision":{"post":{"operationId":"v3-CreateSafeProvisioningRequest","summary":"Create a safe, new device provisioning request.","description":"Creates a new device provisioning request for the specified project, region, and registry using the provided device serial number and access token. If the device has already been provisioned with a different algorithm/secret, it will return an error 409 denoting the conflict.\n","tags":["Provisioning"],"requestBody":{"description":"Device provisioning request object.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"$ref":"#/components/schemas/ProjectId"},"region_id":{"type":"integer","description":"The ID of the region associated with the device.","example":1},"registry_id":{"type":"integer","description":"The ID of the registry associated with the device.","example":456},"serial_number":{"$ref":"#/components/schemas/SerialNumberStrict"},"asset_type_id":{"type":"integer","description":"The ID of the asset type associated with the device. Defaults to 2 (IoT Device).","example":2},"access_token":{"type":"string","description":"The access token required to provision the device.","example":"12345"},"algorithm":{"$ref":"#/components/schemas/Algorithm"},"secret":{"$ref":"#/components/schemas/Secret"}}}}}},"responses":{"200":{"description":"The device provisioning request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"The response data.","properties":{"configuration":{"type":"object","description":"The Configuration of the device","example":{}},"mqtt":{"$ref":"#/components/schemas/MQTT"}}}}}}}},"400":{"$ref":"#/components/responses/Error400"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"}}},"put":{"operationId":"v3-CreateForcefulProvisioningRequest","summary":"Create a forceful, new device provisioning request.","description":"Creates a new device provisioning request for the specified project, region, and registry using the provided device serial number and access token. It will set the algorithm/secret according to the request data, no matter if it was already provisioned or not\n","tags":["Provisioning"],"requestBody":{"description":"Device provisioning request object.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"$ref":"#/components/schemas/ProjectId"},"region_id":{"type":"integer","description":"The ID of the region associated with the device.","example":1},"registry_id":{"type":"integer","description":"The ID of the registry associated with the device.","example":456},"serial_number":{"$ref":"#/components/schemas/SerialNumberStrict"},"asset_type_id":{"type":"integer","description":"The ID of the asset type associated with the device. Defaults to 2 (IoT Device).","example":2},"access_token":{"type":"string","description":"The access token required to provision the device.","example":"12345"},"algorithm":{"$ref":"#/components/schemas/Algorithm"},"secret":{"$ref":"#/components/schemas/Secret"}}}}}},"responses":{"200":{"description":"The device provisioning request was successful.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"The response data.","properties":{"configuration":{"type":"object","description":"The Configuration of the device","example":{}},"mqtt":{"$ref":"#/components/schemas/MQTT"}}}}}}}},"400":{"$ref":"#/components/responses/Error400"},"404":{"$ref":"#/components/responses/Error404"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}/heartbeat":{"post":{"tags":["HeartBeat"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-SendHeartbeatEvent","summary":"Send a heartbeat event","description":"Send a heartbeat event and will trigger reboot event if uptime is smaller than the last one.","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"uptime":{"$ref":"#/components/schemas/Uptime"}}}}}},"responses":{"200":{"description":"The heartbeat event has been sent correctly","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"}}}}}},"400":{"$ref":"#/components/responses/Error400"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}":{"get":{"tags":["Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-GetDevice","summary":"Get device configuration","description":"Get the device's type, configuration, pending configuration (pending command) and metadata","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The device was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceResponseContent"}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}},"delete":{"tags":["Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-DeleteDevice","summary":"Delete a Device","description":"Delete the device with the provided serial number","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"responses":{"200":{"description":"The device was deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"The response status which is either \"success\" or \"error\"","example":"success"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices":{"post":{"tags":["Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-CreateDevice","summary":"Store a Device","description":"Store a new Device with the provided serial number into the registry","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"}],"requestBody":{"description":"The new device's data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serial_number":{"$ref":"#/components/schemas/SerialNumberStrict"},"name":{"type":"string","description":"Optional name for user reference only. Defaults to Serial Number when empty.","example":"12345"},"asset_type_id":{"$ref":"#/components/schemas/AssetTypeId"}}}}}},"responses":{"200":{"description":"The device was created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceResponseContent"}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}/set-authorization":{"post":{"tags":["Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-SetDeviceAuthorization","summary":"Configure authorization for the device","description":"Upload an authorization key","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"}],"requestBody":{"description":"New authorization data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"algorithm":{"$ref":"#/components/schemas/Algorithm"},"secret":{"$ref":"#/components/schemas/Secret"}}}}}},"responses":{"200":{"description":"The new authorization key has successfully been uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"}}}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}},"/api/v3/projects/{project_id}/regions/{region_id}/registries/{registry_id}/devices/{serial_number}/configuration":{"post":{"tags":["Devices"],"security":[{"oAuthFundamentum":[]}],"operationId":"v3-UpdateDeviceConfiguration","summary":"Update Device Configuration or Metadata","description":"Create a command to update the device configuration. Once applied, the actual device configuration will be updated in the cloud twin. Metadata updates are instantaneous.\n","parameters":[{"$ref":"#/components/parameters/projectId"},{"$ref":"#/components/parameters/regionId"},{"$ref":"#/components/parameters/registryId"},{"$ref":"#/components/parameters/serialNumberStrict"},{"in":"query","name":"force","schema":{"type":"boolean"},"description":"Forces the device configuration update. <br><br> Instead of sending a configuration command to the device and assigning the configuration value to `pending configuration`, this request will directly update the `configuration` field in the cloud without communicating the change to the device. Usually, the `configuration` field's value is changed when the device sends a confirmation that it received the new configuration. <br><br> `force` defaults to false if not specified.\n"}],"requestBody":{"description":"Although the fields `configuration` or `meta_data` are marked optional, at least one of them has to be provided, otherwise it will cause an error 422.\n","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configuration":{"$ref":"#/components/schemas/Configuration"},"meta_data":{"$ref":"#/components/schemas/MetaData"}}}}}},"responses":{"200":{"description":"The device's configuration and/or meta data has successfully been updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceResponseContent"}}}},"400":{"$ref":"#/components/responses/Error400"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}}},"tags":[]}