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.3
- 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 |
deactivated
bool
|
True if home has been deactivated by project admin. | 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 |
dataStreamId
string
|
Optional stream ID for bulk data upload. | 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 |
isConnected
boolean
|
Device is currently connected to MODE Cloud via a websocket or MQTT connection. | 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 |
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, an authorized program, or the MODE platform itself 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:
|
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 |