Skip to content

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_days sets 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

Returns 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
email 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.

GET/share/all

Returns 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

POST/share

Creates 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
email 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

{
    "success": "Device link shared successfully"
}

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.

PUT/share

Updates 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
email 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

{
    "success": "Shared device link updated successfully"
}

Failures: Shared device link not found., Permission denied., Invalid access level: ..., Failed to update shared device.

DELETE/share

Deletes 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:

{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl"
}

Response

{
    "success": "Link deleted successfully"
}

Failures: Shared info not found, Not allowed.

Shared device data

GET/share/data

Returns 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:

{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJkZXZpY2VfaWQiOjF9.c2lnbmF0dXJl"
}

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)

GET/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.