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.
| Method | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| GET api/v1/index |
Gets the list of available api endpoints. |
DeviceMeasurementsSummary
Get summary measurements (daily, hourly aggregated) for a device.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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).
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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).
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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).
| API | Description |
|---|---|
| POST api/v1/sigfox/data/uplink |
POST Sigfox uplink data. Supports both UPLINK and BIDIR. |
AlexaBot
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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
| API | Description |
|---|---|
| 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..
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| 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. |
TheThingsNetworkUplink
Handled Uplink data from The Things Network V2
| API | Description |
|---|---|
| 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.
| API | Description |
|---|---|
| GET api/v1/user/{userId}/notificationSettings/options |
No documentation available. |
LifxBots
| API | Description |
|---|---|
| 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 |