Skip to content

Share Links ​

Share specific entities (accessories, rooms, collections) via link. Supports public, passcode-protected, and user-specific access. Create and manage shares from the dashboard's Share dialog — right-click a home, room, or group in the sidebar (Share Home, Share Room, Share Group), or use the top-right ⋯ menu → Share on touch. See Sharing Access for the walkthrough.

Permissions: Only home owners and admins can create and manage share links. Members with control or view roles can open the dialog but can't change it.

Share dialog

Entity types ​

TypeDescription
accessorySingle accessory
accessory_groupGroup of accessories
roomAll accessories in a room
room_groupMultiple rooms
collectionCustom accessory grouping
collection_groupMultiple collections
homeEntire home
groupGeneric group

Access types ​

TypeDescription
publicAnyone with the link can access
passcodeRequires a passcode to access
userOnly the specified Homecast user can access. API only — the dashboard doesn't create these; invite a home member instead. The user must already have a Homecast account

Access roles ​

RolePermissions
viewRead-only — see accessory state
controlRead and write — toggle, adjust, execute

Create a share ​

graphql
# Public share with view access
mutation {
  createEntityAccess(
    entityType: "room"
    entityId: "room-uuid"
    accessType: "public"
    role: "view"
    homeId: "home-uuid"
  ) {
    success
    entityAccess { id }
    shareHash
    shareUrl
  }
}

# Passcode-protected share with control access
mutation {
  createEntityAccess(
    entityType: "accessory"
    entityId: "acc-uuid"
    accessType: "passcode"
    passcode: "1234"
    role: "control"
    homeId: "home-uuid"
    name: "Guest Access"
  ) {
    success
    shareHash
    shareUrl
  }
}

# User-specific share
mutation {
  createEntityAccess(
    entityType: "collection"
    entityId: "coll-uuid"
    accessType: "user"
    userEmail: "friend@example.com"
    role: "control"
    homeId: "home-uuid"
  ) {
    success
  }
}

Share URLs ​

Share links follow the format: https://homecast.cloud/s/{hash}

The hash encodes the entity type, entity ID, and an HMAC signature. Each entity has one link; its public and passcode access entries all hang off that same URL. Users visiting the link see a read-only or interactive view depending on the role. When a passcode with a stronger role exists, a view-only visitor can enter it to unlock control.

Share state endpoint ​

Read the current state of all accessories in a share. Works with any role (view or control).

PathMethodDescription
/s/{hash}GETReturns current accessory state as JSON

Query parameters:

ParameterDescription
passcodeRequired for passcode-protected shares
accessoryFilter to a specific accessory by ID prefix

Example:

bash
curl https://api.homecast.cloud/s/{hash}

Response:

json
{
  "success": true,
  "entity_type": "room",
  "role": "view",
  "accessories": [
    {
      "id": "...",
      "name": "Living Room Light",
      "reachable": true,
      "room": "Living Room",
      "services": [
        {
          "serviceType": "lightbulb",
          "characteristics": [
            { "characteristicType": "on", "value": true, "isWritable": true },
            { "characteristicType": "brightness", "value": 75, "isWritable": true }
          ]
        }
      ]
    }
  ]
}

Share control endpoints ​

For control role shares, accessories can be controlled via simple URL paths:

PathDescription
/s/{hash}/onTurn on
/s/{hash}/offTurn off
/s/{hash}/toggleToggle power state
/s/{hash}/lockLock
/s/{hash}/unlockUnlock
/s/{hash}/brightness/{value}Set brightness (0–100)
/s/{hash}/hue/{value}Set hue (0–360)
/s/{hash}/saturation/{value}Set saturation (0–100)
/s/{hash}/temp/{value}Set color temperature
/s/{hash}/position/{value}Set position (0–100)
/s/{hash}/color/{hue}/{saturation}Set color

These endpoints accept both GET and POST requests.

Access schedules ​

Entity access supports time-based schedules via the accessSchedule argument (a JSON string). In the dashboard, only passcodes can have a schedule (Limited Access in Add Passcode); through the API any access entry can.

json
{
  "starts_at": "2026-07-01T15:00:00Z",
  "expires_at": "2026-07-08T11:00:00Z",
  "time_windows": [
    { "days": ["mon", "tue", "wed", "thu", "fri"], "start": "08:00", "end": "18:00" }
  ],
  "timezone": "Europe/London"
}
FieldMeaning
starts_atAccess refused before this time ("Access not yet active")
expires_atAccess refused after this time ("Access has expired")
time_windowsAccess allowed only inside one of these windows. days uses mon–sun; start/end are HH:MM, inclusive
timezoneIANA timezone the windows are evaluated in (default UTC)

All fields are optional and combine. The schedule is checked on every request. A window must start and end on the same day — 22:00–06:00 never matches; split it into two windows. The dashboard offers times in 30-minute steps up to 23:30.

Manage shares ​

View all shared items from Settings → Sharing → Shared Items.

Shared items

graphql
# List shares for an entity
{ entityAccess(entityType: "room", entityId: "room-uuid") {
    id accessType role name userEmail hasPasscode createdAt
} }

# Get sharing summary
{ sharingInfo(entityType: "room", entityId: "room-uuid") {
    isShared hasPublic publicRole passcodeCount userCount shareHash shareUrl
} }

# Update a share
mutation { updateEntityAccess(accessId: "access-uuid", role: "view") { success } }

# Delete a share
mutation { deleteEntityAccess(accessId: "access-uuid") { success } }

# List all entities I've shared
{ mySharedEntities { id entityType entityId accessType role createdAt } }

Public entity access (no auth required) ​

graphql
# View shared entity
{ publicEntity(shareHash: "abc123", passcode: "1234") {
    entityType entityId entityName homeName accessories { id name }
} }

# Get full accessory data
{ publicEntityAccessories(shareHash: "abc123") {
    id name services { type characteristics { type value } }
} }

# Control an accessory via shared access
mutation {
  publicEntitySetCharacteristic(
    shareHash: "abc123"
    accessoryId: "acc-uuid"
    characteristicType: "on"
    value: true
  ) {
    success
  }
}