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: `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