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.

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.

Media

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

Get all of the (current) users media items.

GET api/v1/media/{id}

Get the individual media item

GET api/v1/media/user/{userOrDeviceId}?start={start}&limit={limit}

Get all of the specified users media items.

GET api/v1/media/user/{userOrDeviceId}/latest

Get all of the users media items.

POST api/v1/media

Upload a media item.

DELETE api/v1/media/{id}

No documentation available.

POST api/v1/media/{id}/tag

No documentation available.

GET api/v1/status/{statusId}/media

Get the list of media attached to the status post.

GET api/v1/media/ByUniqueName/{name}?start={start}&limit={limit}

Returns all the media items assigned with the unique media name. This acts as a kind of perma-link to a every changing image (e.g. time delayed snapshots)

GET api/v1/media/ByUniqueName/{name}/latest

Returns the latest media item currently assigned to the unique media name. This acts as a kind of perma-link to a every changing image (e.g. time delayed snapshots)

GET api/v1/media/UniqueNames

List the unique names for media published (Unique names are unique account wide)

SigfoxService

APIDescription
POST api/v1/sigfox/service/status

POST service status (Not implemented)

POST api/v1/sigfox/service/geoloc

Set a more accurate location for the device from a Sigfox Service -> GEOLOC callback

POST api/v1/sigfox/service/acknowledge

POST acknowledge callback from Sigfox for a downlink (BiDIR) request response to indicate the message was received by the device

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.

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.

SparkBots

Particle Bot Api. See Particle for Devices

APIDescription
GET api/v1/bots/sparkbots

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

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

Get a specific ParticleBot by id.

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

Gets the devices associated with the particle bot.

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

Gets the sims associated with the particle bot.

POST api/v1/bots/sparkbots

Register a bot account.

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

Modify ParticleBot details

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.

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

Create a Tinamous device for the Particle device (where the Particle bot has been set to not auto-add or the device has been disassociated).

SenML

Sensor measurements in the SenML format.

APIDescription
POST api/v1/senml

Submit a new sensor measurement or multiple sensor measurements.

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.

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.

VirtualDeviceBots

APIDescription
GET api/v1/bots/virtualdevicebots

Get all LifxBots for the current account.

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

Get a specific LifxBot by id.

POST api/v1/bots/virtualdevicebots

Register a LifxBot

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

Delete Bot.

TwitterBot

APIDescription
GET api/v1/bots/twitterbots

Get all The Twitter Bots for the current account.

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

Get a specific Twitter Bot by id.

POST api/v1/bots/twitterbots

Create a Twitter Bot.

PUT api/v1/bots/twitterbots/{id}

Modify TwitterBot details

POST api/v1/bots/twitterbots/{id}/Deauthenticate

De-Authenticate the bot from the assigned twitter account.

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

Delete the Twitter Bot.

POST api/v1/bots/twitterbots/{id}/SendTestTweet

Send a test tweet for the bot

GET api/v1/bots/twitterbots/{id}/Tweets

Get the tweets send by the bot

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.

SigfoxDevices

For device details on Sigfox devices.

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

Get Sigfox specific details about the device.

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

Update the sigfox details stored for the device.

TheThingsNetworkBot

APIDescription
GET api/v1/bots/thethingsnetworkbots

Get all The Things Network Bots for the current account. (should this also be filtered on the user?)

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

Get a specific TheThingsNetworkBotDto by id.

POST api/v1/bots/thethingsnetworkbots

Create a The Things Network Bot.

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

Delete Bot.

DeviceLite

APIDescription
GET api/v1/devices/lite

Get the collection of devices assigned to the current user.

Devices

Api for devices to add, update and remove devices.

APIDescription
GET api/v1/devices?tagged[0]={tagged[0]}&tagged[1]={tagged[1]}&batteryPoweredOnly={batteryPoweredOnly}&onlyMyDevices={onlyMyDevices}&reportingOnly={reportingOnly}&offset={offset}&limit={limit}

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}?offset={offset}&limit={limit}

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.

PUT api/v1/devices/{id}/Purge

Purge device data before the specified date (if date not specified, now is used).

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.

Particle

Particle Device API. See SparkBots for bot functions.

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.

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

Gets the SIMS used for the device

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/add

Add a new member.

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.

Tags

Helper API to list various tags.

APIDescription
GET api/v1/tags/users

List the tags associated with the accounts users (members/devices/bots).

GET api/v1/tags/devices

List the tags associated with the accounts devices.

GET api/v1/tags/members

List the tags associated with the accounts devices.

GET api/v1/tags/fields

List the tags associated with the accounts device's fields.

SigfoxData

Endpoint for Sigfox data upload and bidir (uplink and downlink).

APIDescription
POST api/v1/sigfox/data/uplink

POST Sigfox uplink data. Supports both UPLINK and BIDIR.

AlexaBot

APIDescription
GET api/v1/bots/alexabots

Get all The Alexa Bots for the current account.

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

Get a specific AlexaBot by id.

POST api/v1/bots/alexabots

Create an Alexa Bot.

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

Delete the Alexa Bot.

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.

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

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.

TheThingsNetworkV3

Handled Uplink data from The Things Network V3

APIDescription
POST api/v1/thethingsnetwork/v3/join

Join Accept data from The Things Network

POST api/v1/thethingsnetwork/v3/uplink

Upload data from The Things Network HTTP Integration V3.

POST api/v1/thethingsnetwork/v3/downlinkevent

Downlink event (ack, nack, queued and sent)

POST api/v1/thethingsnetwork/v3/downlinkfailed

Downlink failed from The Things Network

POST api/v1/thethingsnetwork/v3/locationsolved

No documentation available.

POST api/v1/thethingsnetwork/v3/servicedata

No documentation available.

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.

BttnPressed

Handler for bt.tn device. Add a Http action to your buttons and get messages or counts for the device.

APIDescription
POST api/v1/bttn/Pressed

Handle bt.tn web request. To use this, add a HTTP Action HTTP Method: POST Agruments: Format: application/json Example Body: { "Message":"Button Pressed" } Posts a "Button Pressed" message onto the timelie Example Body: { "Name":"@lt;NAME@gt;" "DeviceId":"@lt;DEVICEID@gt;" "Counter":"@lt;COUNTER@gt;" "EventType":"@lt;ETYPE@gt;" "CounterPressed":"@lt;COUNTERP@gt;" "CounterLongPressed":"@lt;COUNTERL@gt;" "CounterNotPressed"::"@lt;COUNTERN@gt;" } Sets device measurements for counter, counter pressed, counter long pressed and counter not pressed. Http Authentication: Yes. Use your desired device login.

Handled Uplink data from The Things Network V2

APIDescription
POST api/v1/thethingsnetwork/data/uplink

Upload data from The Things Network HTTP Integration

UserNotificationOptions

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

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

No documentation available.

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