Device sharing¶
A device owner can share a device's history with anyone by email. Each share creates a share link containing a token; the recipient receives an email with a link to a public, read-only page showing the device's recent history (no login required).
Rules:
- A device can have at most 5 share links.
- A device can be shared with the same email address only once (delete the existing link first).
history_dayssets how many days of history the link shows.expires_in_days(optional) sets when the link stops working. Without it the link does not expire.- Shareable device types:
sensor,switch,met,batmon,ws,gps,ping/device.
Access levels (access_level):
| Value | Description |
|---|---|
| read-only | View only |
| read-write | Stored with the link |
| admin | Stored with the link |
| custom | Stored with the link |
The access level is stored and returned with the link; the public view is always read-only.
Every endpoint is also available under a /dashboard prefix (e.g. /dashboard/share, /dashboard/share/all, /dashboard/share/data, /dashboard/shared/view/{token}) with identical behaviour.
Get share link¶
/shareReturns the details of one share link
Request¶
Auth: api_key (query param or cookie)
Request body:
The token can be sent as a query parameter or in a JSON body.
| Field name | Description | Type |
|---|---|---|
| token | Token of the share link | str |
Request example:
https://spoilerinterface.com/interface/share?api_key=8f14e45fceea167a5a36dedd4bea2543&token=eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl
Response¶
{
"success": {
"share_id": "gAAAAABmUJx2c2hhcmVfaWRfZXhh",
"device_id": 301659085216623,
"device_name": "Door sensor",
"device_type": "sensor",
"email": "user@example.com",
"history_days": 5,
"access_level": "read-only",
"expires_at": 1719145472,
"link": "https://spoilerinterface.com/dashboard/shared/view/eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl",
"comment": "Shared with the site manager"
}
}
Field description¶
| Field name | Description | Type |
|---|---|---|
| share_id | ID of the share link, used to edit it | str |
| device_id / device_name / device_type | Shared device | int / str |
| Recipient email | str | |
| history_days | Days of history visible through the link | int |
| access_level | Access level | str |
| expires_at | Expiry time in epoch seconds (null = never) |
int |
| link | Public view URL sent to the recipient | str |
| token | Share token | str |
| comment | Owner's comment | str |
Failures: Missing field: token, Invalid or expired link, Invalid token.
List share links¶
/share/allReturns all share links created by the user
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/share/all?api_key=8f14e45fceea167a5a36dedd4bea2543
Response¶
An array of objects with the same fields as Get share link:
{
"success": [
{
"share_id": "gAAAAABmUJx2c2hhcmVfaWRfZXhh",
"device_id": 301659085216623,
"device_name": "Door sensor",
"device_type": "sensor",
"email": "user@example.com",
"history_days": 5,
"access_level": "read-only",
"expires_at": null,
"link": "https://spoilerinterface.com/dashboard/shared/view/eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl",
"comment": null
}
]
}
Expired links are included in this list.
Share device¶
/shareCreates a share link for a device and emails it to the recipient
Request¶
Auth: api_key (query param or cookie); the device must belong to the caller · Content-type: application/json
Request body:
The request body must be a JSON object:
| Field name | Description | Type |
|---|---|---|
| device_id | ID of the device | int |
| device_type | Device type (see rules above) | str |
| Recipient email | str | |
| history_days | Days of history visible through the link | int |
| access_level | read-only, read-write, admin or custom |
str |
| expires_in_days | [Optional] Days until the link expires. Never expires if omitted | int |
| comment | [Optional] Comment stored with the link | str |
| force | [Optional] When the device is already shared with this email, true re-sends the notification email instead of failing |
bool |
Request example:
{
"device_id": 301659085216623,
"device_type": "sensor",
"email": "user@example.com",
"history_days": 5,
"expires_in_days": 30,
"access_level": "read-only",
"comment": "Shared with the site manager"
}
Response¶
Failures: Maximum number of links reached for the device. Please consider removing unused links., Permission denied., Device information not found, Invalid access level: ..., The device has already been shared with the user <email>. Please delete the existing entry before proceeding., Failed to share device.
Update share link¶
/shareUpdates the settings of an existing share link
Request¶
Auth: api_key (query param or cookie); only the device owner can edit · Content-type: application/json
Request body:
All settings are replaced: an omitted expires_in_days removes the expiry and an omitted comment clears the comment. The token (and therefore the link URL) does not change, and no email is sent.
| Field name | Description | Type |
|---|---|---|
| share_id | share_id of the link |
str |
| Recipient email | str | |
| history_days | Days of history visible through the link | int |
| access_level | read-only, read-write, admin or custom |
str |
| expires_in_days | [Optional] Days from now until the link expires | int |
| comment | [Optional] Comment | str |
Request example:
{
"share_id": "gAAAAABmUJx2c2hhcmVfaWRfZXhh",
"email": "user@example.com",
"history_days": 10,
"expires_in_days": 14,
"access_level": "read-only",
"comment": "Extended history"
}
Response¶
Failures: Shared device link not found., Permission denied., Invalid access level: ..., Failed to update shared device.
Delete share link¶
/shareDeletes a share link; the public link stops working immediately
Request¶
Auth: api_key (query param or cookie); only the device owner can delete · Content-type: application/json
Request body:
| Field name | Description | Type |
|---|---|---|
| token | Token of the share link | str |
Request example:
Response¶
Failures: Shared info not found, Not allowed.
Shared device data¶
/share/dataReturns the history data visible through a share link
Request¶
Auth: None (the share token identifies the device) · Content-type: application/json
Request body:
The token must be sent in a JSON body (not as a query parameter). The last history_days days of history are returned, up to 10000 records.
| Field name | Description | Type |
|---|---|---|
| token | Token of the share link | str |
Request example:
Response¶
{
"success": {
"device_id": 301659085216623,
"device_name": "Door sensor",
"device_type": "sensor",
"min_time": 1716121472,
"max_time": 1716553472,
"data": [
{
"sensor_value": 21.5,
"update_time": "2024-05-24T12:10:00"
}
]
}
}
Field description¶
| Field name | Description | Type |
|---|---|---|
| min_time / max_time | Covered period (epoch seconds) | int |
| data | History records. The keys depend on the device type, matching the history endpoints of each device page (e.g. Sensor, Switch, GPS). Times are shifted by the owner's time offset | arr |
Failures: Invalid token, Token has expired, Shared link/device information not found., Invalid device information, The device does not have history data.
Shared view (public page)¶
/shared/view/{token}HTML page showing the shared device's history; this is the link emailed to the recipient
Request¶
Auth: None (the share token identifies the device)
Request body:
None. {token} is the share token.
Request example:
https://spoilerinterface.com/interface/shared/view/eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl
Response¶
An HTML page (text/html) with the device name, type and the last history_days days of history. A deleted, revoked, expired or invalid link returns HTTP 404 with Invalid or expired link.