Authentication

All communications with Tinamous should use HTTPS to ensure your data is secured, this is especially true when authenticating, particularly with HTTP BASIC and API Token as every request includes information the attacker can easily use to gain access to that user/device account.

MethodDescription
Forms Standard ASP.NET Forms based authentication is supported by default for all API actions.
HTTP Basic You can perform authentication using the standard HTTP Basic Authentication username:password Base64 encoded into the request header. See Wikipedia HTTP Basic Authentication for more details.
Api Token For connecting devices an API key can be generated and passed through as a query string or post parameter. This needs to be enabled for the device and should only be used as a last resort, however it may be useful for devices that don't support the Tinamous API and only support a Form HTTP POST. API Token access is only possible for bots and devices and should be explicitly enabled.
Inbound Email Naturally receipt does not support authentication. Your Tinamous account can be configured to allow email from any source, this is done by means of the Manage account page (or the Account API). If you do not allow emails to be posted from any sender then the From field of the email address needs to match that of a registered user, device or bot, or alternatively be listed in the email whitelist which is a account wide whitelist. User, device and bot accounts support both primary email addresses and email aliases. Should you wish to post emails to Tinamous as a specific user but using different email addresses (e.g. home or work), configure your primary email address as the address Tinamous should send to, then add email aliases so when an email comes from them it will be shown as coming from the specific user. Email also supports blacklist which is defined at the account level and can be used to block specific email addresses from posting to your timeline.

Access Control

Tinamous uses claims based authorization, you should configure the device/bots accounts to be as restrictive as possible.
e.g. if a device only posts measurements you should disable all other api access, including reading of measurements.

DateTime

Helper service to allow devices to look up the current date/time.

APIDescription
GET api/v1/datetime/{format}

Returns the UTC DateTime in various formats.

GET api/v1/datetime/zones

Gets a list of the supported time zones.

GET api/v1/datetime/zones/{id}/{format}

Gets the date time corrected for the timezone id.

Particle

APIDescription
GET api/v1/devices/{deviceId}/particle

Get Particle.io specific details about the device.

POST api/v1/devices/{deviceId}/particle

Create a particle device (requires the particle device to exist really just associated the particle device with this device.)

PUT api/v1/devices/{deviceId}/particle

Update the particle details stored for the device.

POST api/v1/devices/{deviceId}/particle/Invoke/{methodName}

Invoke a method on the particle device.

POST api/v1/devices/{deviceId}/particle/ReadVariables

Read the variable values from the device. Reads all variables defined on the device. Note that this is a HTTP POST as it is an action to read the variables which results in a new measurement being created for the variable set.

GET api/v1/devices/{deviceId}/particle/Variable/{variable}

Read the variable values from the device. Reads all variables defined on the device. Note that this is a HTTP POST as it is an action to read the variables which results in a new measurement being created for the variable set.

POST api/v1/devices/{deviceId}/particle/Refresh

Read the variable values from the device. Reads all variables defined on the device. Note that this is a HTTP POST as it is an action to read the variables which results in a new measurement being created for the variable set.

DeviceMeasurements

Get measurements for a specific device.

APIDescription
GET api/v1/devices/{deviceId}/measurements/channel/{channel}?startDate={startDate}&endDate={endDate}&limit={limit}&sortOrder={sortOrder}&aggregation={aggregation}

Get the measurements for the device/channel. Returns measurements in SenML format. this method returns [limit] points from the [endDate] upto the [startDate]. If Ascending sort order is requested these points are listed in earliest measurement date first ranging to maximum measurement date, however if the [limit] number of points has been met then the earliest measurement date may not have reached the start date. The caller is required to make further calls with the [endDate] set to the minimum measurement date received in the previous page. If their are more than [limit] points the data set is limited that number of points working backwards from the end date.

GET api/v1/devices/{deviceId}/measurements/channel/{channel}/field/{field}?startDate={startDate}&endDate={endDate}&limit={limit}&sortOrder={sortOrder}&aggregation={aggregation}

Get measurements for the specified device field. NB: This uses a different route to fit in better with the /devices/id/... format. If the device allows anonymous access this method will return the measurements without the need for authentication.

GET api/v1/devices/{deviceId}/measurements/channel/{channel}/field/{field}/latest

Gets latest measurement for specified field

Devices

Api for devices to add, update and remove devices.

APIDescription
GET api/v1/devices

Get the collection of devices assigned to the current user.

GET api/v1/devices/{id}

Gets the device specified by the id.

GET api/v1/devices/ByType/{type}

Returns a simple summary list of devices by the type specified.

POST api/v1/devices

Adds a device.

PUT api/v1/devices/{id}

Update the device.

DELETE api/v1/devices/{id}

Delete the device specified

DeviceLocation

Gets the devices location (current/history).

APIDescription
GET api/v1/devices/{deviceId}/location/current

Get the devices current location (Not implemented

GET api/v1/devices/{deviceId}/location?sortOrder={sortOrder}&startDate={startDate}&endDate={endDate}

Get the devices location history.

POST api/v1/devices/{deviceId}/location

Set the devices current location. Use this in preference to setting the location object of the device when updating.

Account

Account management.

APIDescription
GET api/v1/account

Gets the details of the account (the one the current user belongs to).

GET api/v1/account/{id}

Gets the account by Id.

GET api/v1/account/Statistics

Gets the statistics for the account.

PUT api/v1/account/{id}

Put changes to account.

DeviceMeasurementsSummary

Get summary measurements (daily, hourly aggregated) for a device.

APIDescription
GET api/v1/devices/{deviceId}/measurements/summary?startDate={startDate}&endDate={endDate}&aggregationPeriod={aggregationPeriod}

Summary (aggregated) measurements for the device. Includes all channels/fields. This includes min, max, average, count etc.

GET api/v1/devices/{deviceId}/measurements/channel/{channel}/field/{field}/summary?startDate={startDate}&endDate={endDate}&aggregationPeriod={aggregationPeriod}

Summary (aggregated) measurements for the channel/field. This includes min, max, average, count etc.

UserNotificationSettings

Responsible for user notification configuration. (e.g. sending email/txt etc).

APIDescription
GET api/v1/user/{userId}/notificationSettings

Returns the logged in users notification settings for actions performed by the specified forUserId user/device/bot.

GET api/v1/user/{userId}/notificationSettings/{id}

Returns the logged in users specific notification settings by Id.

POST api/v1/user/{userId}/notificationSettings

Create a new notification option for the current user.

POST api/v1/user/{userId}/notificationSettings/{id}/Enable

Enable the notification

POST api/v1/user/{userId}/notificationSettings/{id}/Disable

Enable the notification

DELETE api/v1/user/{userId}/notificationSettings/{id}

Delete (disable) ALL the notification option for the user.

POST api/v1/user/{userId}/notificationSettings/{id}/Reset

No documentation available.

Exports

Data Exports

APIDescription
GET api/v1/exports?limit={limit}

Get all the exports available for the current user.

GET api/v1/exports/device/{deviceId}/measurements

Get the exported measurements for the specified device.

POST api/v1/exports/device/{deviceId}/measurements

Request export of measurements for the device.

DELETE api/v1/exports/{id}

Delete the specified export.

Status

Responsible for timeline status messages

APIDescription
GET api/v1/Status?startDate={startDate}&endDate={endDate}&userNames={userNames}&limit={limit}

Get time-line status posts. All messages appropriate for the logged in user (their posts, general posts or messages they are mentioned in).

GET api/v1/Status/{id}

Get status message by Id.

POST api/v1/Status

Submit a new status message.

DELETE api/v1/Status/{id}

Delete status messages is not supported.

Alerts

Responsible for raising and showing alerts to the user.

APIDescription
GET api/v1/alerts?start={start}&limit={limit}

Get the alerts.

GET api/v1/alerts/Summary

Returns the summary of the alerts (counts of each type)

POST api/v1/alerts

Raise a new alert.

PUT api/v1/alerts/{id}

Modify existing alert.

PATCH api/v1/alerts/{id}

Modify existing alert.

PUT api/v1/alerts/ClearAll?alertLevel={alertLevel}

Clear all of the outstanding alerts of a particular alert level.

LifxBots

APIDescription
GET api/v1/bots/lifxbots

Get all LifxBots for the current account.

GET api/v1/bots/lifxbots/{id}

Get a specific LifxBot by id.

POST api/v1/bots/lifxbots

Register a LifxBot

DELETE api/v1/bots/lifxbots/{id}

Delete Bot.

GET api/v1/bots/lifxbots/{id}/Scenes

List the scenes available to the LifxBot

DeviceChartsMeasurements

Gets the Measurement field points for device charts. NB: Uses aggregated rates for speed/size depending on the range selected. Do not use if you are interested in individual measurements..

APIDescription
GET api/v1/devices/{deviceId}/charts/{chartId}/measurements/channel/{channel}?startDate={startDate}&endDate={endDate}&limit={limit}&aggregationThreshold={aggregationThreshold}&rangeType={rangeType}

Get the measurements for the device/channel in a chartable (aggregated) format. this method returns [limit] points from the [endDate] upto the [startDate]. If Ascending sort order is requested these points are listed in earliest measurement date first ranging to maximum measurement date, however if the [limit] number of points has been met then the earliest measurement date may not have reached the start date. The caller is required to make further calls with the [endDate] set to the minimum measurement date received in the previous page. If their are more than [limit] points the data set is limited that number of points working backwards from the end date.

GET api/v1/devices/{deviceId}/charts/{chartId}/measurements/channel/{channel}/field/{field}?startDate={startDate}&endDate={endDate}&limit={limit}&aggregationThreshold={aggregationThreshold}&rangeType={rangeType}

Get measurements for the specified device field. NB: This uses a different route to fit in better with the /devices/id/... format. If the device allows anonymous access this method will return the measurements without the need for authentication.

User

Responsible for getting details about a user or the list of users for the account

APIDescription
GET api/v1/user

Get all users for the current account.

GET api/v1/user/{id}

Get a specific user by id.

GET api/v1/user/{userName}

Gets a specific user by user-name.

POST api/v1/user

Register a user account.

POST api/v1/user/requestPasswordReset

User requests a password reset. Sends an email to allow the user to reset their password.

PUT api/v1/user/passwordReset

Reset the user's password. Uses HTTP PUT to reset the user's password from the token supplied in the password reset email.

POST api/v1/user/invite

Invite a user to the join the Tinamous account.

Measurements

Handles Measurements posted to Tinamous from devices.

APIDescription
GET api/v1/measurements/{deviceId}/{channel}?startDate={startDate}&endDate={endDate}&limit={limit}&sortOrder={sortOrder}

Get measurements for the specified device/user.

POST api/v1/measurements

Submit a new measurement. Use SenML Post in preference to this api to allow for better naming of fields.

Index

Contents api to act as the root of the api and provide links to resources.

APIDescription
GET api/v1/index

Gets the list of available api endpoints.

SparkBots

APIDescription
GET api/v1/bots/sparkbots

Get all SparkBots for the current account. (should this also be filtered on the user?)

GET api/v1/bots/sparkbots/{id}

Get a specific SparkBot by id.

GET api/v1/bots/sparkbots/{id}/Devices

Gets the devices associated with the particle bot.

POST api/v1/bots/sparkbots

Register a bot account.

PUT api/v1/bots/sparkbots/{id}/Authenticate

Re-authenticate spark bot. This is needed after the spark access token expires.

DELETE api/v1/bots/sparkbots/{id}

Delete Bot.

POST api/v1/bots/sparkbots/{id}/RefreshDevices

Request check new and changed devices associated with the ParticleBot.

POST api/v1/bots/sparkbots/{id}/Associate/{particleDeviceId}

Associate the Particle device with a Tinamous device.

POST api/v1/bots/sparkbots/{id}/Disassociate/{particleDeviceId}

Disassociate the particle device from the currently assigned device.

SenML

Sensor measurements in the SenML format.

APIDescription
POST api/v1/senml

Submit a new sensor measurement or multiple sensor measurements.

UserNotificationOptions

Describes the options available for a user when creating a notification.

APIDescription
GET api/v1/user/{userId}/notificationSettings/options

No documentation available.