Documentation for the new WIFIPUG API. Only accepts JSON body input, and defaults to JSON output, add .json or .xml to any route to specify a response file type.

Default request content-types: application/json
Default response content-types: application/json, text/xml
Base URL: http://api.wifiplug.co.uk

Summary

Devices

Operation Description
GET /device
POST /device
POST /device/bind
GET /device/{id}
POST /device/{id}
DELETE /device/{id}
POST /device/{id}/boost
POST /device/{id}/control
GET /device/{id}/energy
POST /device/{id}/link
GET /device/{id}/timer
POST /device/{id}/timer

Timers

Operation Description
POST /device/{id}/boost
GET /device/{id}/energy
GET /device/{id}/timer
POST /group/{id}/boost
GET /group/{id}/energy
GET /group/{id}/timer

Groups

Operation Description
GET /group
GET /group/{id}
POST /group/{id}
POST /group/{id}/add
POST /group/{id}/boost
POST /group/{id}/control
GET /group/{id}/energy
POST /group/{id}/remove
GET /group/{id}/timer
POST /group/{id}/timer

Users

Operation Description
GET /user
POST /user
POST /user/login
POST /user/register
GET /user/verify?email={email}&verificationToken={verificationToken}

Security

basicAuth

description: Used to provide API key/secret authentication. All requests to the API must have a valid basicAuth pair attached. The `username` is the given API key, and the `password` is the given API secret.

sessionToken

description: For all customers except pre-approved Enterprise and in-house applications (`XAuth` clients), the sessionToken is obtained via the standard oAuth 2 flow. If you are an `XAuth` client, please consult the `/user/login` and `/user/register` endpoints below.
authorizationUrl: https://api.wifiplug.co.uk/oauth/authorize
tokenUrl: https://api.wifiplug.co.uk/oauth/token
flow: accessCode

Paths

GET /device

Tags: Device

Gets a list of devices associated with the session token if provided, or the user that owns if the API key if no session token is provided.

Uses default content-types: application/json text/xml

200 OK

An array of devices.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

basicAuth
sessionToken

POST /device

Tags: Device

For legacy devices only. Ties a 1st Generation WIFIPLUG Mini or POWER to the account.

macAddress

The Mac address to bind to this account.

formData string
name

The new name for this device.

formData string
type

The type of device being added.

formData integer
firmwareVersion

The firmware version of the device being added. Provide "v0" if data is not available.

formData string

Uses default content-types: application/json text/xml

200 OK

A device object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

basicAuth
sessionToken device

POST /device/bind

Tags: Device

Gets a one time token, which should be sent to the WIFIPLUG Home plug in order to configure it on our network. Requires a custom client, as this process is handled via our Android and iOS apps ordinarily. Your API key must be authorised by us beforehand in order to use this route.

Uses default content-types: application/json text/xml

200 OK

The one time token to transmit to the plug.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

basicAuth
sessionToken device

DELETE /device/{id}

Tags: Device

Deletes a specified device, assuming the user is authenticated successfully.

id

the device ID to query, update, or delete.

path string

Uses default content-types: application/json text/xml

200 OK

Device was deleted successfully - returns an empty object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

GET /device/{id}

Tags: Device

Gets a specified device, assuming the user is authenticated correctly.

id

the device ID to query, update, or delete.

path string

Uses default content-types: application/json text/xml

200 OK

A device object.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken

POST /device/{id}

Tags: Device

Updates a specified device, assuming the user is authenticated correctly.

id

the device ID to query, update, or delete.

path string
name

The new name of the device.

formData string
description

A new description for the device.

formData string

Uses default content-types: application/json text/xml

200 OK

A device object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken device

POST /device/{id}/boost

Tags: Device, Timer

Turns a plug on for the specified amount of time, before turning it back off again. If the plug is already turned on, then the device is simply switched off after the specified amount of time.

id

The device ID to control.

path string
duration

The length of time, in seconds, that the device should be switched on for.

formData integer

Uses default content-types: application/json text/xml

200 OK

A timer object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

POST /device/{id}/control

Tags: Device

Allows a device to be controlled

id

the device ID to query, update, or delete.

path string
type

The type of action to carry out. For plugs, this type is always "switch".

formData string
value

The value to set. If the plug is turning on, then true. If turning off, then false.

formData boolean

Uses default content-types: application/json text/xml

200 OK

A device object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

GET /device/{id}/energy

Tags: Device, Timer

Gets the latest energy count for a device. Enterprise customers, see separate documentation for details on how to access socket connection for live data.

id

the device ID to query.

path string

Uses default content-types: application/json text/xml

200 OK

The energy details for this particular device or group.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

403 Forbidden

The current authentication status is forbidden to access this endpoint.

basicAuth
sessionToken energy

POST /device/{id}/link

Tags: Device

Allows another user to control this device.

id

the device ID to query.

path string
username

The username to add to this plug.

formData string

Uses default content-types: application/json text/xml

200 OK

A device object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

403 Forbidden

The current authentication status is forbidden to access this endpoint.

basicAuth
sessionToken device , control

GET /device/{id}/timer

Tags: Device, Timer

Gets a list of timers associated with a device.

id

the device ID to query, update, or delete.

path string

Uses default content-types: application/json text/xml

200 OK

A list of timers

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken

POST /device/{id}/timer

Tags: Device

Create a new timer for a device.

id

the device ID to query.

path string
time

The GMT time, in the 24h form nn:nn, that the timer should execute.

formData string
isRepeated

If the timer is repeated. If isRepeated is true and no repeats parameter is passed, then it is assumed that the timer repeats at the same time daily.

formData boolean
repeats

If isRepeated is true, then repeats is an array of the format [n, n, n, n, n, n, n] where n is 0 or 1. This represents each day of the week, where array[0] is a Sunday. For example, [0, 1, 1, 1, 1, 1, 0] would repeat each day from Monday-Friday.

formData integer[] , multiple parameters (repeats=aaa&repeats=bbb)

Uses default content-types: application/json text/xml

200 OK

A timer object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

GET /group

Tags: Group

Gets the groups associated with this API key or the session token, if applicable.

Uses default content-types: application/json text/xml

200 OK

An array of groups

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No object matching the specified query was found.

basicAuth
sessionToken

GET /group/{id}

Tags: Group

Gets the details of a group with a specific ID.

id

the group ID to query.

path string

Uses default content-types: application/json text/xml

200 OK

A group of devices.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No object matching the specified query was found.

basicAuth
sessionToken

POST /group/{id}

Tags: Group

Updates the details of a group.

id

The group ID to query.

path string
name

The new name of the group.

formData string

Uses default content-types: application/json text/xml

200 OK

A group of devices.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No object matching the specified query was found.

basicAuth
sessionToken device

POST /group/{id}/add

Tags: Group

Adds a device to a group.

id

The group ID to add a new device to.

path string
device

The ID of the device to add to the group.

formData string

Uses default content-types: application/json text/xml

200 OK

A group of devices.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken device

POST /group/{id}/boost

Tags: Group, Timer

Turns all the devices in a group on for the specified amount of time, before turning it back off again. If the plug is already turned on, then the device is simply switched off after the specified amount of time.

id

The group ID to set a boost for.

path string
duration

The length of time, in seconds, that the devices in the group should be switched on for.

formData integer

Uses default content-types: application/json text/xml

200 OK

A timer object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

POST /group/{id}/control

Tags: Group

Allows a group of devices to be controlled. If only a subset of the group's devices can carry out the requested action, then those devices will carry out the action.

id

The group ID to control.

path string
type

The type of action to carry out. At the moment, this type is always "switch".

formData string
value

The value to set. If the group is being turned on, then true. If turning off, then false.

formData boolean

Uses default content-types: application/json text/xml

200 OK

A group of devices.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

GET /group/{id}/energy

Tags: Group, Timer

Gets the latest energy count for a group of devices. Enterprise customers, see separate documentation for details on how to access socket connection for live data.

id

The group ID to get energy for.

path string

Uses default content-types: application/json text/xml

200 OK

The energy details for this particular device or group.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

403 Forbidden

The current authentication status is forbidden to access this endpoint.

basicAuth
sessionToken energy

POST /group/{id}/remove

Tags: Group

Removes a device from a group.

id

The group ID to remove the device from.

path string
device

The ID of the device to remove from the group.

formData string

Uses default content-types: application/json text/xml

200 OK

A group of devices.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken device

GET /group/{id}/timer

Tags: Group, Timer

Gets a list of timers associated with a group.

id

The group ID to get timers for.

path string

Uses default content-types: application/json text/xml

200 OK

A list of timers

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken

POST /group/{id}/timer

Tags: Group

Create a new timer for a group.

id

the group ID to create a timer for.

path string
time

The GMT time, in the 24h form nn:nn, that the timer should execute.

formData string
isRepeated

If the timer is repeated. If isRepeated is true and no repeats parameter is passed, then it is assumed that the timer repeats at the same time daily.

formData boolean
repeats

If isRepeated is true, then repeats is an array of the format [n, n, n, n, n, n, n] where n is 0 or 1. This represents each day of the week, where array[0] is a Sunday. For example, [0, 1, 1, 1, 1, 1, 0] would repeat each day from Monday-Friday.

formData integer[] , multiple parameters (repeats=aaa&repeats=bbb)

Uses default content-types: application/json text/xml

200 OK

A timer object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No device with that ID tied to authenticated account was found.

basicAuth
sessionToken control

GET /user

Tags: User

Gets the profile of the currently signed in user.

Uses default content-types: application/json text/xml

200 OK

A user object.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

404 Not Found

No object matching the specified query was found.

basicAuth
sessionToken

POST /user

Tags: User

Allows the currently signed in user to be updated.

Uses default content-types: application/json text/xml

200 OK

A user object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

403 Forbidden

The current authentication status is forbidden to access this endpoint.

basicAuth
sessionToken user

POST /user/login

Tags: User

Allows a user to be logged in. For pre-approved (XAuth) clients only. For all other clients, use the oAuth endpoints.

Uses default content-types: application/json

The username and password.

Uses default content-types: application/json text/xml

200 OK

A user object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

403 Forbidden

The account's email address has not been verified yet.

basicAuth

POST /user/register

Tags: User

Allows a user to register. Requires email verification before the account is active. For pre-approved (XAuth) clients only. For all other clients, use the oAuth endpoints.

Uses default content-types: application/json

The details of the new account.

Uses default content-types: application/json text/xml

200 OK

The account's email address has not been verified yet.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

basicAuth

GET /user/verify?email={email}&verificationToken={verificationToken}

Tags: User

Allows a user to verify their email address. Required before the account is active. For pre-approved (XAuth) clients only. For all other clients, use the oAuth endpoints.

email

The email we are verifying.

path string
verificationToken

The token sent to the user upon verification.

path string

Uses default content-types: application/json text/xml

200 OK

A user object.

400 Bad Request

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

401 Unauthorized

The sessionToken or API key/secret provided were invalid.

basicAuth

Response definitions

unauthorized

The sessionToken or API key/secret provided were invalid.

user

A user object.

device

A device object.

deviceList

An array of devices.

energy

The energy details for this particular device or group.

deviceNotFound

No device with that ID tied to authenticated account was found.

userNotFound

No object matching the specified query was found.

unverified

The account's email address has not been verified yet.

badRequest

All of the required fields were not filled, or invalid data was provided in the request. Further information will be provided in the message field of the response.

forbidden

The current authentication status is forbidden to access this endpoint.

token

The one time token to transmit to the plug.

timer

A timer object.

timerList

A list of timers

group

A group of devices.

groupList

An array of groups

Schema definitions

Characteristic: object

uuid: string

The UUID of this characteristic

type: string

A human-readable type for this characteristic.

status: boolean

The current status of the device. For now, if the device is currently powered on or not.

lastUpdated: integer

A UNIX timestamp of when the device was last updated.

power: integer

The last power reading from the device.

voltage: integer

The last voltage reading from the device.

current: integer

The last current reading from the device.

energy: integer

The last energy reading from the device.

Device: object

id: string

A UUID for this device.

owners: object[]
macAddress: string

The MAC address of the device.

type: string , x ∈ { 0 , 1 }

The device type.

firmwareVersion: string

The current version of firmware on the device.

name: string

The name of the device.

status: boolean

If the device is currently connected to our server or not.

characteristics: object[]

DeviceList: object

devices: object[]

Energy: object

status: boolean
power: number

TODO - value/units

voltage: number

TODO - value/units

current: number

TODO - value/units

history: object[]

Error: object

success: boolean

Always false.

code: integer

The error code.

message: string

A human-readable description of the error.

Group: object

id: string

A UUID for this group.

name: string
characteristic: Characteristic
devices: object[]

GroupList: object

groups: object[]

LiveEnergy: object

datetime: string
power: number
voltage: number
current: number

OneTimeToken: object

token: string

Timer: object

id: string

A UUID for this timer.

target: Timer_target
time: string

THe GMT time, in the 24h form nn:nn, that the timer should execute.

isRepeated: boolean

If the timer is repeated. Or not. If it is, then repeats is also passed.

repeats: number[]

If isRepeated is true, then repeats is an array of the format [n, n, n, n, n, n, n] where n is 0 or 1. This represents each day of the week, where array[0] is a Sunday. For example, [0, 1, 1, 1, 1, 1, 0] would repeat each day from Monday-Friday.

number

Timer_target: object

type: string , x ∈ { device , group }

The type of object the timer is for. Presently, this is either device or group.

id: string

The UUID of the target.

TimerList: object

timers: object[]

User: object

id: string

A UUID for this user.

email: string
firstName: string
lastName: string
sessionToken: string

Only returned on a login endpoint.

UserPass: object

username: string

The email address to log in with.

password: string

The password to log in with.

UserRegistration: object

email: string
password: string
firstName: string
lastName: string