api.flair.co

Versioning

*NOTE: Until there is an actual release of Flair hardware, or we announce otherwise, we will break API compatibility regularly without changing the version information. *

The Flair API is versioned RESTfully using media types. By default, clients requesting either, Accept: application/vnd.api+json or Accept: application/json or Accept: */* will receive the newest version of the API media type. In order to request a specific version of an API resource you MUST request the application/vnd.api+json media type and add further version information to the Accept header eg: Accept: appliation/vnd.api+json; co.flair.api.version=1.

We will support deprecated API version for 6 months after a deprecation announcement.

Authorization

The Flair API uses OAuth2 for Authorization. We support all OAuth workflows. Only Authorized Users, 'Partners', may register OAuth clients with the API. Contact partners@flair.co for more information.

Scopes

All scopes are divided into '.view' and '.edit' varities. Clients with view permissions may only make GET requests for the resources, while those with both the view and edit scopes may make any kind of request for scopes. A Resources's required scopes are noted in the resource documentation below.

Clients using the implicit grant may only request '.view' scopes.

/oauth/authorize

Third parties and request Authorization here by redirecting the user to a url like /oauth/authorize?client_id={application id}&redirect_uri={uri to return the user to}&scope={comma separated list of scopes}&state={state to verify the request wasnt tampered with}.

/oauth/token

Registered clients may request credentials through this endpoint.

Client Credentials

Request:

{
    "client_id": "the application id",
    "client_secret": "the application secret",
    "scopes": "comma seperated list of scopes",
    "grant_type": "client credentials"
}

Response:

{
    "access_token": "6JwgO77PApxsFCU8Quz0pnL9s23016",
    "refresh_token": "7cYSMmBg4T7F4kwoWfUQA99J8yqjp0",
    'token_type": "Bearer",
    "expires_in": 3600,
    "scope": "users.view structures.view events.view"
}

Resource Owner Credentials

Request:

{
    "client_id": "the application id",
    "client_secret": "the application secret",
    "username": "the user's email address",
    "password": "the users's password",
    "scopes": "comma seperated list of scopes",
    "grant_type": "password"
}

Response:

{
    "access_token": "6JwgO77PApxsFCU8Quz0pnL9s23016",
    "refresh_token": "7cYSMmBg4T7F4kwoWfUQA99J8yqjp0",
    'token_type": "Bearer",
    "expires_in": 3600,
    "scope": "users.view structures.view events.view"
}

Access Grant

Request:

{
    "client_id": "the application id",
    "client_secret": "the application secret",
    "code": "the access code from the authorization step",
    "state": "the state from the authorzation step",
    "grant_type": "authorization_code"
}

Response:

{
    "access_token": "6JwgO77PApxsFCU8Quz0pnL9s23016",
    "refresh_token": "7cYSMmBg4T7F4kwoWfUQA99J8yqjp0",
    'token_type": "Bearer",
    "expires_in": 3600,
    "scope": "users.view structures.view events.view"
}

JSON API

JSON API is a specification for HATEOAS APIs using JSON as their base media type. It uses the application/vnd.api+json as its media type and clients SHOULD set both their Accept and Content-Type headers to that media type, though the Flair API will be more lax than the specification on this count.

JSON API describes a standard method for CRUD actions against API resources and how to describe and modify relationships between resources using hypermedia. The full spec is available here, but people interacting with the the API will probably want to use a pre-existing client implementation.

A JSON API resource representation looks like:

{
    "links": {
        "self": "/api/user/1"
    },
    "data": {
        "id": "1",
        "type": "users",
        "attributes": {
            "name": "edpaget",
            "temparature-scale": "K"
        },
        "relationships": {
            "viewable-structures": {
                "self": "/api/users/1/relationships/viewable-structures",
                "related": "/api/users/1/viewable-structures",
                "data": [{
                    "id": "2",
                    "type": "structures"
                }]

            },
             "editable-structures": {
                "self": "/api/users/1/relationships/editable-structures",
                "related": "/api/users/1/editable-structures",
                "data": [{
                    "id": "1",
                    "type": "structures"
                }]

            },
            "adminable-structures": {
                "self": "/api/users/1/relationships/adminable-structures",
                "related": "/api/users/1/adminable-structures",
                "data": [{
                    "id": "3",
                    "type": "structures"
                }]
            }
        }
    },
    "included": [{
        "id": "2",
        "type": "structures",
        "attributes": {
            "name": "Summer Home",
        },
        "relationships": {
            "rooms": {
                "self": "/api/structures/2/relationships/rooms",
                "related": "/api/structures/2/rooms"
            }
        },
        "links": {
            "self": "/api/structures/2"
        }
    }]
}

Error Objects look like: json { "errors": { "title": "Not Found", "code": "404", "detail": "users resource with id 2 was not found" } }

A request to create a resource:

POST /api/structures json { "data": { "type": "structures", "attributes": { "name": "Winter Home" }, "relationships": { "admin-users": [{ "id": "1", "type": "users" }] } } }

A request to update a resource:

PUT /api/users/2 json { "data": { "id": "1", "type": "users", "attributes": { "name": "Will Paget" } } }

The API

/api

The root will return a listing of all the other routes on the API. Something like

{
    "users": {
        "href": "/users",
        "type": "users"
    }
}

/api/applications

Management for OAuth applications. Accessible to partners.

Scope: applications

Attributes

Attr Type Editable? Description
name string Yes Name for the application. This will be displayed to users on the authorization page
description string Yes Brief description of the application. This will be displayed to users on the authorizations page
client_id string No OAuth id of the application
client_secret string No Randomly generated secret key for the application
redirect_uris array[string] Yes List of uris the application is allowed to redirect to after successful authorization. The first item is the default uri used if one is not specified
scopes array[string] Yes List of scopes the application may request. Used as the default scope request if none are specified in the authorization step

Links

Link Type Editable? Description
user users No Owning user of the application. When using the client credentials workflow this is the user the token will be issued for.
callbacks callbacks Yes Web hooks and their event types the application has registered

/api/callbacks

OAuth Applications can register and modify callbacks when vents, pucks, or sensors change.

Scope: applications

Attributes

Attr Type Editable? Description
webhookurl url Yes URL to POST the webhook payload to
event_type string Yes Type of event that triggers the webhook

Links

Link Type Editable? Description
structure structures No Structure whose changes will trigger the webhook
application applications No Application that registered the webhook

/api/users

Scope: users

Attributes

Attr Type Editable? Description
name string Yes Uh...the name of the user
email string Yes User's email address

Links

Link Type Editable? Description
viewable-structures structures Yes Structures which a user only has permission to view
edtiable-structures structures Yes Structures which a user only has permission to edit
adminable-structures structures Yes Structures which a user only has permission to admin

/api/structures

Scope: structures

Attributes

Attr Type Editable? Description
name string Yes Shorthand name for this structure
structure_type integer Yes 0 - Central HVAC, 1 - Window Unit or Split Unit
mode integer Yes I forget
location string Yes Location of the structure as either a Zip Code, Street Address, or Lat/Lng coordinates.
location-type integer Yes 0 - Address, 1 - Zipcode, 2 - Lat/Lng

Links

Link Type Editable? Description
viewer-users users Yes User with only permission to view this structure
editor-users users Yes User with only permission to edit this structure
admin-users users Yes User with only permission to admin this structure
rooms rooms Yes Rooms within this structure
zones zones Yes Zones within this structure
thermostats thermostats Yes The thermostats connected to this structure
weather-readings weather-readings No List of weather readings flair has recorded to optimize settings for this structure
pucks pucks Yes Pucks within this structure
vents vents Yes Vents within this structure

/api/zones

Zones are grouping of rooms controlled by a single thermostat in a multi-thermostat structure.

Scope: structures

Attributes

Attr Type Editable? Description
name string Yes Name for this zone

Links

Link Type Editable? Description
structure structures Yes The structure this zone belongs to
rooms rooms Yes Rooms that have been added to this zone
thermostat thermostats Yes Thermostat that controls this zone

/api/rooms

Scope: structures

Attributes

Attr Type Editable? Description
name string Yes Name for this room
level string Yes The level of the structure this room is on
air-return boolean yes Does this room has a return air feed with a filter
windows Array[Object[String,String]] yes list of windows and the direction they face

Links

Link Type Editable? Description
structure structures Yes Structure this room is within
zone zones Yes Zone this room is optionally part of
pucks pucks Yes Pucks in this room
vents vents Yes Vents in this room

/api/vents

Returns both the desired state of the vent and the previous state that was known to the API.

Scope: structures

Attributes

Attr Type Editable? Description
name string Yes Short hand name for the vent
current-vent-state object yes-ish Desired state of the vent. The fields in this object are listed below
current-vent-state.precent-open integer Yes The amount the vent should be open
current-vent-state.battery-level decimal No Amount of battery remaining in the vent
current-vent-state.lights string Yes The pattern of the lights on the vent
current-vent-state.demo-mode boolean No Set the vent to demo-mode
current-vent-state.update-interval integer No ???
previous-vent-state object No The state of the vent the last time it was synced with the API. The fields in this object are listed below
previous-vent-state.precent-open integer No The amount the vent should be open
previous-vent-state.battery-level decimal No Amount of battery remaining in the vent
previous-vent-state.lights string No The pattern of the lights on the vent
previous-vent-state.demo-mode boolean No Set the vent to demo-mode
previous-vent-state.update-interval integer No ???

Links

Link Type Editable? Description
room rooms Yes The room the vent is in
sensor-readings vent-sensor-readings No Readings from the vent sensors

/api/vent-sensor-readings

Reports form the vent's sensors

Scope: structures

Attributes

Attr Type Editable? Description
duct-temperature-c decimal No Temperature at the vent
duct-pressure decimal No Pressure at the vent
rssi integer No ???

Links

Link Type Editable? Description
vent vents No Vent the reading were taken for

/api/pucks

Returns both the desired state of the puck and the previous state that was known to the API.

Scope: structures

Attributes

Attr Type Editable? Description
name string Yes Short hand name for the puck
current-puck-state object yes-ish Desired state of the puck. The fields are listed below.
current-puck-state.battery-level decimal No Amount of battery remaining in the puck
current-puck-state.gateway boolean Yes Whether this puck is the gateway for the flair setup
previous-puck-state object No Desired state of the puck. The fields are listed below.
previous-puck-state.battery-level decimal No Amount of battery remaining in the puck
previous-puck-state.gateway boolean No Whether this puck is the gateway for the flair setup

Links

Link Type Editable? Description
room rooms Yes The room the puck is in
beacon-sightings beacon-sightings No List of recent beacon sightings from the puck's ibeacon
sensor-readings sensor-readings No List of readings from the puck's sensors
puck-apps puck-apps Yes Apps running on the puck

/api/puck-apps

Puck apps represent tasks the puck can do, eg act as a TV remote, act as a room thermostat.

Scope: puck-apps

Attributes

Attr Type Editable? Description
app-type string No The type of the app (temp-control, tv-remove, etc)
app-state object Yes freeform object describing the puck-app state

Links

Link Type Editable? Description
puck pucks Yes The puck this app should be running on

/api/thermostats

Scope: thermostats

Attributes

Attr Type Editable? Description
make string No The manufacturer of the thermostat
model string No The model of the thermostat
name string Yes A shorthand name for this thermostat

Links

Link Type Editable? Description
room rooms Yes The room the thermostat is in
structure structures Yes The structure the thermostat is in
thermostat-states thermostat-states No Readings from the thermostat

/api/thermostat-states

Scope: thermostats

Attributes

Attr Type Editable? Description
target-temperature-c decimal No The user's set temperature
ambient-temperature-c decimal No The thermostat's current temperature reading

Links

Link Type Editable? Description
thermostat thermostats No The thermostat that generated these readings

/api/beacon-sightings

Scope: sensors

Attributes

Attr Type Editable? Description
rssi integer No ???
txpower integer No ??? - Android Only
distance float No Distance from the beacon -- Android Only
bluetooth-name string No Name of the phone's bluetooth device -- Android Only
bluetooth-mac string No The MAC address of the phone's bluetooth device -- Android Only
observer-wifi-mac string No The MAC address of the phone's wifi -- Android Only
observer-device-uuid uuid No Device uuid -- iOS Only
distance-string string No String description of the distance from the beacon -- iOS only
description string No ??? -- iOS only
accuracy float No Estimate of distance accuracy -- iOS only

Links

Link Type Editable? Description
puck pucks No The puck this beacon is attached to

/api/sensor-readings

Scope: sensors

Attributes

Attr Type Editable? Description
room-temperature-c float No The measured room temperature
room-pressure float No Measured atmospheric pressure in the room
humidity float No Measured humidity in the room
rssi integer No Signal strength indicator
message-version integer No ???

Links

Link Type Editable? Description
puck pucks No The puck this sensor is attached to

/api/weather-readings

Scope: sensors

Attributes

Attr Type Editable? Description
sunrise DateTime No When the run will rise on the day of the reading
sunset DateTime No When the run will set on the day of the reading
outside-temperature-c decimal No Current outside temperature
windspeed decimal No current windspeed
wind-direction decimal No Direction of the wind
humidity decimal No Outdoor humidity
pressure decimal No Outdoor air pressure
wind-chill decimal No Outdoor wind chill
condition string No Outdoor weather condition

Links

Link Type Editable? Description
structure structures No The structure the weather reading was taken for

/api/devices

Devices a user has used to access their Flair account

Scope: users

Attributes

Attr Type Editable? Description
user-agent string No UserAgent string recorded on login

Links

Link Type Editable? Description
user users No The User who logged in on this device
beacon-sightings beacon-sightings No Beacon sightings involving this device

/api/hvac-units

Information about HVAC devices (central units/windows units/splits/heaters) within a structure

Attributes

Attr Type Editable? Description
make string yes Manufacturer of the unit
model stirng yes Model number of the unit
name string yes short name for the user to refer to the unit by
current-state.temperature float yes desired temperature setting of the unit
current-state.power boolean yes desired power on/off setting of the unit
current-state.mode integer yes 0 - Cooling, 1 - for Heating (if supported)
current-state.fan-speed float yes desired unit fan speed (if supported)
previous-state.temperature float no last known temperature setting of the unit
previous-state.power boolean no last known power on/off setting of the unit
previous-state.mode integer no 0 - Cooling, 1 - for Heating (if supported)
previous-state.fan-speed float no last known unit fan speed (if supported)

Links

Link Type Editable? Description
room rooms yes The Room the unit is in
structure structures yes The Structure the unit is in (if not attached to a room)