API Reference: Data Models

This is the full list of data models used by the MODE cloud API. They are expected to be sent to or received from the API in JSON format.

Version
2.1
Base URL
https://api.tinkermode.com

User

A registered end-user of a project.

Type Description Mutable
id
integer
Unique user ID assigned at time of creation. No
projectId
integer
Project that this user belongs to. No
creationTime
string
Timestamp of user registration. No
phoneNumber
string
A valid phone number with country code. Present if project uses phone numbers to uniquely identify users. No
email
string
A valid email address. Present if project uses email addresses to uniquely identify users. No
password
string
Used only when creating or updating a user who logs in by email/password. Yes
name
string
Display name of user. Yes
verified
boolean
Account is verified. No

Home

Represents a home which contains devices and is managed by one or more users.

Type Description Mutable
id
integer
Unique ID assigned at time of creation. No
projectId
integer
Project that this home belongs to. No
creationTime
string
Timestamp of home creation. No
name
string
Display name of home. Yes
timezone
string
(Deprecated. Do not use for new projects.) Timezone name as used in tzdata. Yes
Example:
{
  "id":9,
  "projectId":11,
  "creationTime":"2015-04-21T00:16:22.381Z",
  "name":"My Home"
}

Home Member

A memeber of a home.

Type Description Mutable
userId
integer
User ID of home member. No
creationTime
string
Timestamp when member was added to home. No
name
string
Display name of member. No
phoneNumber
string
Phone number used by member. No
email
string
Email address of member. No
verified
boolean
True if member is a verified user. No
Example:
{
  "userId":1,
  "creationTime":"2015-04-22T19:49:26.245Z",
  "name":"Gaku Ueda",
  "phoneNumber":"+16501234567",
  "verified":true
}

Smart Module

Definition of a Smart Module created for a project.

Type Description Mutable
id
string
Smart Module ID. Must be unique within the project. No
moduleType
string
Type of Smart Module. Must be one of the recognized type IDs. Yes
creationTime
string
Timestamp of entry creation. No
description
string
A short description of the Smart Module. Yes
suspended
bool
Set to true to disable this Smart Module. Yes
subscribedEvents
array
List of event types the Smart Module subscribes to. Yes
configData
object
Configuration data. Used only during creation/update of the Smart Module. Yes

Device

Represents a device instance created by a project.

Type Description Mutable
id
integer
Unique device ID. No
projectId
integer
Project that this device belongs to. No
creationTime
string
Timestamp of device record creation. No
name
string
Display name of device. Yes
tag
string
An optional/informational tag associated with device. Can be used to store the serial number, for example. Yes
deviceClass
string
Device class ID as defined by the project. No
homeId
integer
This property is present if device belongs to a home. Yes
apiKey
string
API access key assigned to device. Usually hidden except to privileged clients, but is also present during the On-Demand Device Provisiong process. No
claimCode
string
Claim code assigned to device. Hidden except to privileged clients. Yes
claimTime
string
Timestamp of device being claimed by a user. No
claimExpirationTime
string
Expiration time of device's claimable state. No
lastConnectTime
string
The last time the device connected to the cloud. No
lastDisconnectTime
string
The last time the device disconnected from the cloud. No
lastCommandTime
string
The last time a command was successfully sent to device. No
lastEventTime
string
The last time the device emitted an event. No

Device Command

Represents a command to be issued to a device. Each class of devices support a specific set of pre-defined commands.

Type Description Mutable
action
string
Action to be taken by device. Yes
parameters
object
Action-specific parameters. This is opaque to the cloud service. Yes
deviceId
integer
ID of the device for which this command is intended. Required if command is routed through a device hub. Yes

Event

Represents an event to be propagated from a device or Smart Module to other listeners.

Type Description Mutable
eventType
string
Event type ID. Project Developers can define any event IDs. Yes
eventData
object
Event-specific data as a JSON hash. Opaque to the cloud service. Yes
timestamp
string
Moment when event was triggered. MODE adds this at event delivery to listeners. Devices don't need to add this. No
homeId
integer
ID of the home associated with this event. MODE adds this at event delivery to listeners. Devices don't need to add this. No
originDeviceId
integer
MODE adds this at event delivery to listeners. This property is present if the event originates from a device. No
originDeviceClass
string
If the event originates from a device, this property is the device's class ID. MODE adds this at event delivery to listener. No
originDeviceIp
string
IP address of device. This property is present if the event originates from a device. MODE adds this at event delivery to listeners. No
originProjectKeyId
string
If the event originates from a project API key, this property is the unique key ID. MODE adds this at event delivery to listener. No
originProjectKeyName
string
If the event originates from a project API key, this property is its display name. MODE adds this at event delivery to listener. No
Example:
{
    "eventType": "sprinkler-status",
    "eventData": {
        "zones": [0,0,0,0,0,0,0,1],
        "serial": 12,
        "timestamp": 1402313424,
        "appSerial": 14,
        "appTimestamp": 14243423423
    }
}

Client Authentication

Contains results of a successful client authentication request.

Type Description Mutable
token
string
Access token to be used in the HTTP Authorization header in future API requests. No
userId
integer
This property is present if token is associated with a user. No

Authentication Info

For inspecting current authentication status of API client.

Type Description Mutable
type
allowed values:
  • user
  • device
  • project key
  • nobody
Type of client entity, or 'nobody' if client is not authenticated. No
userId
integer
This property is present if token is associated with a user. No
appId
string
ID of app used. This property is present if token is associated with a user authenticated via an app. No
deviceId
integer
This property is present if token is associated with a device. No
projectKeyName
string
This property is present if token is assocaited with a project API key. No
projectId
integer
This property is present if token is associated with a project. No

SMS Message Receipt

Info about an outgoing SMS message. Purely for debug purpose.

Type Description Mutable
recipient
string
Phone number receiving the SMS message. No
Example:
{
  "recipient": "+16501234567"
}

Error

For reporting API errors.

Type Description Mutable
reason
string
Reason of error. No
data
object
Any relevant data related to error. No

Registration State Response

Result of a request to change the claim mode of a device instance.

Type Description Mutable
claimExpirationTime
string
Claim Expiration Timestamp No
Example:
{"claimExpirationTime":"2015-04-26T09:36:25.191274242Z"}

User Session Info

Info about the currently active user session.

Type Description Mutable
userId
integer
ID of the user associated with this session. No
appId
string
App used to initiated this session. No
projectId
integer
Project associated with this session. No
creationTime
string
Time when session started. No

Device Provisioning Token

A token issued for a device to complete On-demand Device Provisioning.

Type Description Mutable
token
string
The provisioning token itself. No
expirationTime
string
Expiration time of this token. No

Key-Value Pair

A key-value pair stored for a home.

Type Description Mutable
key
string
Must be unique within each home. Can contain alphanumerical characters, underscores ('_') and dashes ('-'), but must start and end with an alphabet or number. No
value
boolean,string,number,array,object
An arbitrary piece of data assigned to the given key. Yes
modificationTime
string
Timestamp of creation or last modification. No