> For the complete documentation index, see [llms.txt](https://help.runonrufus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.runonrufus.com/public-api/specifications/devices.md).

# Devices

## List devices

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Devices"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"parameters":{"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"1-based page."},"LimitDevices":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":5000},"description":"Max items per page (devices)."}},"schemas":{"DevicesListResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/DeviceSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["description","pagination"]}},"required":["body"]},"DeviceSummary":{"type":"object","additionalProperties":false,"properties":{"deviceid":{"type":"string"},"type":{"type":"string"},"model":{"type":"string"},"alias":{"type":"string"},"firmware":{"type":"string","nullable":true},"serial_number":{"type":"string"},"last_login":{"type":"string","format":"date-time","nullable":true},"creation_date":{"type":"string","format":"date-time","nullable":true},"sessions":{"type":"integer","minimum":0},"device_status":{"type":"string","nullable":true},"battery_percentage":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"charging":{"type":"boolean","nullable":true},"last_telemetry_at":{"type":"string","format":"date-time","nullable":true},"last_reported_latitude":{"type":"number","nullable":true},"last_reported_longitude":{"type":"number","nullable":true}},"required":["deviceid","type","model","alias","serial_number"]},"Pagination":{"type":"object","additionalProperties":false,"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["page","limit","total","has_more"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/devices":{"get":{"tags":["Devices"],"summary":"List devices","description":"Requires `READ` or `READ_WRITE` api key access type.","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/LimitDevices"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicesListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Bind (create) device

> Requires \`WRITE\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Devices"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"BindDeviceRequest":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string"},"model":{"type":"string"},"serial_number":{"type":"string"},"alias":{"type":"string"},"firmware":{"type":"string"}},"required":["type","model","serial_number"]},"BindDeviceResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"deviceid":{"type":"string"},"already_binded":{"type":"boolean","nullable":true}},"required":["description","deviceid"]}},"required":["body"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/devices":{"post":{"tags":["Devices"],"summary":"Bind (create) device","description":"Requires `WRITE` or `READ_WRITE` api key access type.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindDeviceRequest"}}}},"responses":{"201":{"description":"Device binded succesfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindDeviceResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Get device by id

> Requires \`READ\` or \`READ\_WRITE\` api key access type.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Devices"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"DeviceGetResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"result":{"$ref":"#/components/schemas/DeviceDetails"}},"required":["description"]}},"required":["body"]},"DeviceDetails":{"allOf":[{"$ref":"#/components/schemas/DeviceSummary"},{"type":"object","additionalProperties":false,"properties":{"passings":{"type":"integer","minimum":0},"last_seen":{"type":"string","format":"date-time","nullable":true},"battery_volts":{"type":"number","nullable":true},"temperature_celsius":{"type":"integer","nullable":true},"gps_accuracy_m":{"type":"number","nullable":true},"network_type":{"type":"string","nullable":true},"signal_strength":{"type":"integer","nullable":true}}}]},"DeviceSummary":{"type":"object","additionalProperties":false,"properties":{"deviceid":{"type":"string"},"type":{"type":"string"},"model":{"type":"string"},"alias":{"type":"string"},"firmware":{"type":"string","nullable":true},"serial_number":{"type":"string"},"last_login":{"type":"string","format":"date-time","nullable":true},"creation_date":{"type":"string","format":"date-time","nullable":true},"sessions":{"type":"integer","minimum":0},"device_status":{"type":"string","nullable":true},"battery_percentage":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"charging":{"type":"boolean","nullable":true},"last_telemetry_at":{"type":"string","format":"date-time","nullable":true},"last_reported_latitude":{"type":"number","nullable":true},"last_reported_longitude":{"type":"number","nullable":true}},"required":["deviceid","type","model","alias","serial_number"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/devices/{deviceid}":{"get":{"tags":["Devices"],"summary":"Get device by id","description":"Requires `READ` or `READ_WRITE` api key access type.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGetResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Unbind (delete) device

> Requires an api key with \`allow\_unbind=true\`.

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Devices"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"UnbindDeviceResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"deviceid":{"type":"string"}},"required":["description","deviceid"]}},"required":["body"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/devices/{deviceid}":{"delete":{"tags":["Devices"],"summary":"Unbind (delete) device","description":"Requires an api key with `allow_unbind=true`.","responses":{"200":{"description":"Device unbinded succesfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbindDeviceResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```

## Report device telemetry/status

> Requires \`WRITE\` or \`READ\_WRITE\` api key access type.\
> \
> Stale updates are ignored if \`reported\_at\` is older than the current \`last\_telemetry\_at\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"RUFUS Public REST API","version":"0.1.0"},"tags":[{"name":"Devices"}],"servers":[{"url":"https://api.runonrufus.com/v0","description":"Production (v0)"}],"security":[{"ApiKeyHeader":[]},{"XApiKeyHeader":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"api_key","description":"API key for authentication."},"XApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication (alternate header)."}},"schemas":{"DeviceTelemetryRequest":{"type":"object","additionalProperties":false,"description":"At least one telemetry field is required.","properties":{"reported_at":{"type":"string","format":"date-time"},"device_status":{"type":"string"},"battery_percentage":{"type":"integer","minimum":0,"maximum":100},"battery_volts":{"type":"number","minimum":0},"charging":{"type":"boolean"},"temperature_celsius":{"type":"integer","minimum":-100,"maximum":200},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"gps_accuracy_m":{"type":"number","minimum":0},"network_type":{"type":"string"},"signal_strength":{"type":"integer","minimum":-200,"maximum":200}}},"DeviceTelemetryResponse":{"type":"object","additionalProperties":false,"properties":{"body":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string"},"deviceid":{"type":"string"},"result":{"type":"object","additionalProperties":false,"properties":{"deviceid":{"type":"string"},"last_telemetry_at":{"type":"string","format":"date-time"},"device_status":{"type":"string","nullable":true},"battery_percentage":{"type":"integer","nullable":true},"battery_volts":{"type":"number","nullable":true},"charging":{"type":"boolean","nullable":true},"temperature_celsius":{"type":"integer","nullable":true},"last_reported_latitude":{"type":"number","nullable":true},"last_reported_longitude":{"type":"number","nullable":true},"gps_accuracy_m":{"type":"number","nullable":true},"network_type":{"type":"string","nullable":true},"signal_strength":{"type":"integer","nullable":true}}}},"required":["description","deviceid"]}},"required":["body"]},"EnvelopeAny":{"type":"object","additionalProperties":false,"properties":{"body":{"description":"Operation result body."}}},"EnvelopeNull":{"type":"object","additionalProperties":false,"properties":{"body":{"nullable":true}},"required":["body"]}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"PayloadTooLarge":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeAny"}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeNull"}}}}}},"paths":{"/devices/{deviceid}/status":{"patch":{"tags":["Devices"],"summary":"Report device telemetry/status","description":"Requires `WRITE` or `READ_WRITE` api key access type.\n\nStale updates are ignored if `reported_at` is older than the current `last_telemetry_at`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTelemetryRequest"}}}},"responses":{"200":{"description":"Updated (or ignored if stale)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceTelemetryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```