{"openapi":"3.0.1","info":{"title":"Devices API","version":"v1","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}}}},"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/v1/devices/{serial_number}/states":{"post":{"deprecated":true,"tags":["States"],"security":[{"oAuthFundamentum":[]}],"operationId":"v1-CreateDeviceStateEvent","summary":"Create a new state event for a device with given serial number.","description":"Create a new state event for a device with the provided serial number.","parameters":[{"$ref":"#/components/parameters/serialNumber"}],"requestBody":{"description":"State event object that needs to be added.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timestamp":{"type":"integer","description":"The timestamp of the event in milliseconds."},"beacons":{"type":"array","description":"An array of beacons for the device.","items":{"type":"object","properties":{"identification":{"type":"string","description":"The Serial number of the beacon."},"states":{"type":"object","properties":{"rssi":{"type":"number","description":"The RSSI value of the beacon."}}}}}},"states":{"type":"object","description":"An object representing the state of the device."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"More information about the error. This field may be empty depending on error type"}}}}}},"400":{"$ref":"#/components/responses/Error400"}}}},"/api/v1/provision":{"post":{"deprecated":true,"operationId":"v1-CreateProvisioningRequest","summary":"Create a new device provisioning request.","description":"Creates a new device provisioning request using the provided device serial number, access token and public key. This route is not authenticated by the gateway; authentication is handled by the provisioning service.\n","tags":["Provisioning"],"requestBody":{"description":"Device provisioning request object.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"$ref":"#/components/schemas/ProjectId"},"serial_number":{"$ref":"#/components/schemas/SerialNumber"},"access_token":{"type":"string","description":"The access token required to provision the device.","example":"12345"},"public_key":{"$ref":"#/components/schemas/PublicKey"},"asset_type_id":{"type":"integer","description":"The ID of the asset type associated with the device. Defaults to 2 (IoT Device).","example":2}}}}}},"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."}}}}}},"422":{"$ref":"#/components/responses/Error422"}}}},"/api/v1/devices/{serial_number}/heartbeat":{"post":{"deprecated":true,"tags":["HeartBeat"],"security":[{"oAuthFundamentum":[]}],"operationId":"v1-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/serialNumber"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"uptime":{"$ref":"#/components/schemas/Uptime"}}}}}},"responses":{"200":{"description":"Success, contains pending commands in response.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"data":{"type":"object","description":"Device's data","properties":{"commands":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/Error400"}}}},"/api/v1/devices/{serial_number}/commands/{device_command_id}":{"post":{"deprecated":true,"tags":["Commands"],"security":[{"oAuthFundamentum":[]}],"operationId":"v1-UpdateCommandStatus","summary":"Update a command status","description":"Update the status of a device command to ongoing, success or failed","parameters":[{"$ref":"#/components/parameters/serialNumber"},{"in":"path","name":"device_command_id","required":true,"description":"The id of the device command","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/Status"},"message":{"type":"string","description":"The message to describe the changement of status","example":"The command as started on the device"}}}}}},"responses":{"200":{"description":"Success"},"400":{"$ref":"#/components/responses/Error400"}}}}},"tags":[]}