Notes about this documentation. URLs are prefixed with either a GET, POST, PUT or DELETE these document what HTTP verb the request accepts. If the request requires a body it will be prefixed with a Body:.

Authentication

This is the main entry point to the API. You can use this to authenticate and receive an authorization token.

Status
Some users choose to enable authentication. To determine this you can access the status command.

Request

GET /api/auth

Response

Available states.

• uninitilized
• enabled
• disabled

Disable
You can disable the auth system using this call.

Note. You can only disable uninitialized instances.

Request

POST /api/auth/disable

Response

Login
Creates a session for the given user.

Request

POST /api/auth/logon
Body: application/json

Body

Response

The token will be null if authentication has failed. The token can now be used in the authroization header for all other requests to the API.

Logout
Removes the current user's session from the server.

Request

GET /api/auth/logout

Response

Validate
Validates the current session

Request

GET /api/auth/validate

Response

Users

List all users.

Request

GET /api/users

Response

[]

Create
Create a user

Request

PUT /api/users
Body: application/json

Body

User

Fetch a single user.

Request

GET /api/users/:id

Response

Update
Updates a user record.

Request

POST /api/users/:id
Body: application/json

Body

Delete
Deletes a user.

Request

DELETE /api/users/:id

Version

Fetches information about the hoobsd service

Request

GET /api

Response

Service

Fetches the current status of the hub and bridges

Request

GET /api/status

Response

Hostname

Fetch or set the current mDNS broadcast hostname.

Request

GET /api/system/hostname

Response

Update
Change the broadcasted hostname

Request

POST /api/system/hostname
Body: application/json

Body

Response

System

Fetch basic system information

Request

GET /api/system

Response

CPU
Fetch CPU information.

Request

GET /api/system/cpu

Response

Memory
Fetch memory information.

Request

GET /api/system/memory

Response

Network
Fetch network information.

Request

GET /api/system/network

Response

[
    "127.0.0.1"
]

File System
Fetch disk information.

Request

GET /api/system/filesystem

Response

[]

Activity
Fetch process information.

Request

GET /api/system/activity

Response

Temprature
Fetch CPU temprature.

Request

GET /api/system/temp

Response

Backup
Generates a backup file.

Request

GET /api/system/backup

Response

Backups
Fetch a list of stored backups.

Request

GET /api/system/backup/catalog

Response

[]

Files are located in the http://[ip address]/backups/

Restore
Restore from a stored backup.

Request

GET /api/system/restore

Upload a backup file and restore.

Request

POST /api/system/restore
Body: multipart/binary

Upgrade
Upgrade to latest software.

Request

POST /api/system/upgrade

Reboot
Reboot the device.

Request

PUT /api/system/reboot

Shutdown
Shutdown the device.

Request

PUT /api/system/shutdown

Factory Reset
Factorey reset.

Request

PUT /api/system/reset

This will remove all plugins and configs. It will not delete stored backups.

Log

Fetch the log.

Request

GET /api/log/:tail

Tail is not required. It will default to 500

Response

Hub

Fetches the hub configuration.

Request

GET /api/config

Response

Reconfigure
Update the hub configuration.

Request

POST /api/config
Body: application/json

Body

Cache
Fetches the cache from all bridges.

Request

GET /api/cache

Response

[]

Purge
This clears the hub cache.

Request

DELETE /api/cache/purge

Note. This clears the hub cache, not the bridge cache. The hub caches information like sessions, plugin definitions, etc…

Extensions

List extensions and their status.

Request

GET /api/extentions

Response

Note. Extentions are different from plugins. Extentions act on the hub not the bridge.

Enable
Enable an extension.

Request

PUT /api/extentions/:name

Response

Disable
Disable and extension.

Request

DELETE /api/extentions/:name

Response

Bridges

List all bridges.

Request

GET /api/bridges

Response

[]

Create
Creates a bridge.

Request

PUT /api/bridges
Body: application/json

Body

Count
Return a bridge count.

Request

GET /api/bridges/count

Response

Import
Upload and create a bridge from an export file.

Request

POST /api/bridges/import
Body: multipart/binary

Bridge

Update a single bridge.

Request

GET /api/bridge/:bridge

Response

Update
Edit a bridge record.

Request

POST /api/bridge/:id
Body: application/json

Body

Delete
Remove a bridge.

Request

DELETE /api/bridge/:id

Note. Deleting a bridge also removes plugins and stops it from running.

Ports
Update the accessory ports.

Request

POST /api/bridge/:id/ports
Body: application/json

Body

Configuration
Fetches a bridge configuration.

Request

GET /api/config/:bridge

Response

Reconfigure
Update a bridge configuration.

Request

POST /api/config/:bridge
Body: application/json

Body

Plugins
Fetches a list of plugins on a bridge.

Request

GET /api/plugins/:bridge

Response

[]

Cache
Fetches a bridge configuration.

Request

GET /api/cache/:bridge

Response

Purge
Update a bridge configuration.

Request

DELETE /api/cache/:bridge/purge/:uuid

The UUID field is not required. If it is not defined this will purge all accessories and parings.

Export
Export a bridge.

Request

GET /api/bridge/:id/export

Response

Start
Starts a stopped bridge.

Request

POST /api/bridge/:bridge/start

Stop
Stops a running bridge.

Request

POST /api/bridge/:bridge/stop

Restart
Restarts a running or stopped bridge.

Request

POST /api/bridge/:bridge/restart

Plugins

List all installed plugins.

Request

GET /api/plugins

Response

[]

Install
Install a plugin on a bridge.

Request

PUT /api/plugins/:bridge/:name

Response

Note. The name field supports scopes, so if you have a scoped plugin just enter it complete with the slash like @hoobs/plugin. The name field also supports versions @hoobs/[email protected]. If a version is not set it defaults to latest.

Uninstall
Uninstall a plugin from a bridge.

Request

DELETE /api/plugins/:bridge/:name

Response

Note. The name field supports scopes, so if you have a scoped plugin just enter it complete with the slash like @hoobs/plugin.

Update
Update a plugin on a bridge.

Request

POST /api/plugins/:bridge/:name

Response

Note. The name field supports scopes, so if you have a scoped plugin just enter it complete with the slash like @hoobs/plugin. The name field also supports versions @hoobs/[email protected]. If a version is not set it defaults to latest.

Plugin

This section is for UI plugins included with a plugin or via a sidecar. A plugin consists of a routes.js file and a ui folder that contains static files like index.html and app.js. Refer to the UI Plugin Documentation for further details.

Static
Fetch a static file.

Request

GET /ui/plugin/:identifier/*

This returns any static file included with the plugin. It will default to index.html is no file is defined.

Note. If you try to access index.html without a file the trailing slash is important, and must be included.

Action
This section is for UI plugins included with a plugin or via a sidecar.

Request

POST /api/plugin/:identifier/:action
Body: application/json

The response and body is determined by the registered route from the plugin's routes.js file.

Note. Access to the bridge is restricted. If you need to modify values in the bridge use either the API, SDK, or your main plugin.

Accessories

Fetches a list of rooms and accessories.

Request

GET /api/accessories

Response

[]

Get
Fetch a single accessory.

Request

GET /api/accessory/:bridge/:id

Response

Stream
Fetches a video stream for a given camera accessory. This is not available for non camera types.

This requires that the FFMpeg extension is installed, and only supports camera accessories configured with an RTSP stream, for example the Camera FFMpeg plugin.

Request

GET /api/accessory/:bridge/:id/stream

Response
A binary mp4 stream that can be consumed by most video players.

Snapshot
This fetches a snapshot from a camera accessory. This is not available for non camera types.

Request

GET /api/accessory/:bridge/:id/snapshot

Response

iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAABhWlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1Iw0AcxV/TSkWqgn
YQdchQnSyIijhKFYtgobQVWnUwufRDaNKQpLg4Cq4FBz8Wqw4uzro6uAqC4AeIm5uToouU+L+k0CLGg+N+vLv3uHsHCPUy
U83AOKBqlpGKx8RsbkUMviKAPgQxhB6JmXoivZCB5/i6h4+vd1Ge5X3uz9Gt5E0G+ETiWaYbFvE68fSmpXPeJw6zkqQQnx
OPGXRB4keuyy6/cS46LPDMsJFJzRGHicViG8ttzEqGSjxFHFFUjfKFrMsK5y3OarnKmvfkLwzlteU012kOI45FJJCECBlV
bKAMC1FaNVJMpGg/5uEfdPxJcsnk2gAjxzwqUCE5fvA/+N2tWZiccJNCMaDjxbY/RoDgLtCo2fb3sW03TgD/M3CltfyVOj
DzSXqtpUWOgN5t4OK6pcl7wOUOMPCkS4bkSH6aQqEAvJ/RN+WA/luga9XtrbmP0wcgQ10t3QAHh8BokbLXPN7d2d7bv2ea
/f0AO8NykaOwp3oAAAAGYktHRAAAAK0A+eyCP/QAAAAJcEhZcwAALiMAAC4jAXilP3YAAAAHdElNRQflBBIHHAkfKeo5AA
AAGXRFWHRDb21tZW50AENyZWF0ZWQgd2l0aCBHSU1QV4EOFwAAAAxJREFUCNdjYKATAAAAaQABwB3y+AAAAABJRU5ErkJg

This returns a base64 encoded image, if the camara is unavailable, the image will be undefined.

Characteristics
Fetch an array of characteristics for a given accessory.

Request

GET /api/accessory/:bridge/:id/characteristics

Response

[
    "on",
    "brightness",
    "hue",
    "saturation"
]

Update
Updates an accessory including device control.

Request

PUT /api/accessory/:bridge/:id/:service
Body: application/json

Body

You can also change the name, room, sequence, or hidden field using this method.

Hidden
Shows a list of hidden accessories.

Request

GET /api/accessories/hidden

Response

[]

Rooms

Fetches a list of rooms.

Request

GET /api/rooms

Response

[]

Create
Creates a room.

Request

PUT /api/room
Body: application/json

Body

Room

Fetch a single room.

Request

GET /api/room/:id

Response

Update
Updates a room, including device control like all off.

Request

PUT /api/room/:id/:service
Body: application/json

Body

You can also change the name, or sequence using this method.

Remove
Removes a room.

Request

DELETE /api/room/:id

Themes

Fetch a theme.

Request

GET /api/theme/:name

Response

{
    "name": "custom",
    "display": "Custom",
    "auto": false,
    "mode": "dark",
    "transparency": "blur(6px)",
    "application": {
        "text": {
            "default": "#999",
            "highlight": "#fff",
            "input": "#fff",
            "error": "#e30505",
        },
        "background": "#141414",
        "highlight": "#feb400",
        "accent": "#f5ff66",
        "dark": "#252525",
        "drawer": "#111111d2",
        "input": {
            "background": "#262626",
            "accent": "#444",
        },
        "border": "#252525",
    },
    "button": {
        "background": "#252525",
        "text": "#fff",
        "border": "#1a1a1a",
        "primary": {
            "background": "#feb400",
            "text": "#fff",
            "border": "#feb400",
        },
        "light": {
            "background": "#fff",
            "text": "#777",
            "border": "#e5e5e5",
        },
    },
    "modal": {
        "text": {
            "default": "#999",
            "input": "#fff",
            "error": "#e30505",
        },
        "background": "#111111d2",
        "dark": "#000",
        "form": "#11111100",
        "mask": "#14141400",
        "highlight": "#feb400",
        "input": "#262626",
        "accent": "#303030",
        "border": "#252525",
    },
    "widget": {
        "text": {
            "default": "#999",
        },
        "background": "#181818d2",
        "highlight": "#feb400",
        "border": "#252525",
    },
    "menu": {
        "text": {
            "default": "#b4b4b4",
            "highlight": "#fff",
        },
        "background": "#1111119d",
        "highlight": "#1d1d1d9d",
        "border": "#1d1d1d",
    },
    "navigation": {
        "text": {
            "default": "#999",
            "highlight": "#fff",
            "active": "#feb400",
        },
        "background": "#141414",
        "highlight": "#feb400",
        "border": "#4b4b4b",
    },
    "accessory": {
        "text": "#ffffff3d",
        "background": "#302f2f",
        "highlight": "#fff",
        "input": "#414141",
        "border": "#444",
    },
    "backdrop": "url('/defaults/backdrops/default.jpg')",
    "elevation": {
        "default": "0 1px 1px 1px rgba(0, 0, 0, 0.44), 0 -3px 1px -1px ...",
        "button": "0 1px 1px 0 rgba(0, 0, 0, 0.44), 0 2px 1px -1px rgba...",
    },
}

Update
Update a custom theme.

Request

POST /api/theme/:name
Body: application/json

This accepts a theme as defined above.

The light and dark themes are built in and can not be changed.

Backdrop
Upload a custom backdrop image.

Request

POST /api/theme/:name
Body: multipart/binary

Response

{
    "filename": "custom.jpeg"
}

Location

Searches for a location by text.

Request

GET /api/weather/location?query=denver&count=10

Response

[{
    "id": "123456",
    "name": "Denver",
    "country": "United States"
}]

Weather

Fetches the current weather.

Request

GET /api/weather/current

Response

{
    "units": "celsius",
    "weather": 32,
    "description": "sunny",
    "icon": "sunny",
    "temp": 32,
    "min": 32,
    "max": 32,
    "windchill": 31,
    "pressure": 15,
    "humidity": 20,
    "visibility": 10,
    "wind": {
        "speed": 2,
        "direction": 270
    }
}

Note. To get the current weather, you must first set the city id in the hub config.

Forecast
Fetches a weather forecast.

Request

GET /api/weather/forecast

Response

[{
    "units": "celsius",
    "weather": 32,
    "description": "sunny",
    "icon": "sunny",
    "temp": 32,
    "min": 32,
    "max": 32,
    "windchill": 31,
    "pressure": 15,
    "humidity": 20,
    "visibility": 10,
    "wind": {
        "speed": 2,
        "direction": 270
    }
}]

Note. To get the weather forecast, you must first set the city id in the hub config.