Skip to content
Tidepool API/Data API/
/
Update Data Set

Data API (1.0)

The Tidepool API is an HTTP REST API used by Tidepool clients use to communicate with the Tidepool Platform.

For more information, see the Getting Started section.

Download OpenAPI description
data.v1.json
data.v1.yaml
Overview
URL

https://support.tidepool.org/

Tidepool API Support

support@tidepool.org

License

BSD-2-Clause

Terms of Service

Languages
Servers
Mock server

https://tidepool.redocly.app/_mock/reference/data.v1/

integration

https://external.integration.tidepool.org/

production

https://api.tidepool.org/

dev1

https://dev1.dev.tidepool.org/

qa1

https://qa1.development.tidepool.org/

qa2

https://qa2.development.tidepool.org/

Internal

APIs intended for internal use by Tidepool.

Operations

Data

Manages diabetes data in user's Tidepool account.

Operations

Get Data Set

Request

Returns the data set specified by the dataSetId.

Security
sessionToken
Path
dataSetIdstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...required

Data Set ID

Example: ce8cc5f7595575945f91fc6710db6fef
curl -i -X GET \
  https://tidepool.redocly.app/_mock/reference/data.v1/v1/data_sets/ce8cc5f7595575945f91fc6710db6fef \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json
object
Response
application/json
{}

Update Data Set

Request

Updates the data set specified by the dataSetId.

Security
sessionToken
Path
dataSetIdstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...required

Data Set ID

Example: ce8cc5f7595575945f91fc6710db6fef
Bodyapplication/json

Update Data Set

deviceIdstring(Device ID)non-emptyrequired

Globally unique to device and repeatable with each upload, e.g. device make and model with serial number

Example: "MMT-1711:12345678"
deviceModelstring(Device Model Name)non-emptyrequired

A string identifying the model of the device.

The deviceModel is a non-empty string that encodes the model of device. We endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc.

Example: "Devicey McDeviceface"
deviceSerialNumberstring(Device Serial Number)non-emptyrequired

A string encoding the device's serial number.

The deviceSerialNumber is a string that encodes the serial number of the device. Note that even if a manufacturer only uses digits in its serial numbers, the SN should be stored as a string regardless.

Uniquely of string fields in the Tidepool device data models, deviceSerialNumber may be an empty string. This is essentially a compromise: having the device serial number is extremely important (especially for e.g., clinical studies) but in 2016 we came across our first case where we cannot recover the serial number of the device that generated the data: Dexcom G5 data uploaded to Tidepool through Apple iOS's HealthKit integration.

Example: "B97B6D59"
statestring(Data Set State)required
Enum"open""closed"
Example: "open"
timestring(date-time)(Date/Time)required

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
timezonestring(Time Zone)required

A string timezone name from the IANA timezone database

Example: "Europe/London"
timezoneOffsetinteger(int32)(Time Zone offset)[ -10080 .. 10080 ]required

Time zone offset, expressed as positive or negative number of minutes from UTC.

Example: -420
curl -i -X PUT \
  https://tidepool.redocly.app/_mock/reference/data.v1/v1/data_sets/ce8cc5f7595575945f91fc6710db6fef \
  -H 'Content-Type: application/json' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE' \
  -d '{
    "deviceId": "MMT-1711:12345678",
    "deviceModel": "Devicey McDeviceface",
    "deviceSerialNumber": "B97B6D59",
    "state": "open",
    "time": "2017-02-06T02:37:46Z",
    "timezone": "Europe/London",
    "timezoneOffset": -420
  }'

Responses

Data Set

Bodyapplication/json
annotationsArray of Annotation (object) or Blood Glucose Out of Range (object)(Annotation Array)[ 0 .. 100 ] itemsunique

An array of annotations.

byUserstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

clientobject(Client Software)

The client software that provided diabetes data.

clockDriftOffsetinteger(int64)(Clock Drift Offset)[ -86400000 .. 86400000 ]

Clock drift offset, expressed as milliseconds.

Example: 0
computerTimestring(time)(Computer Time)

An ISO 8601 formatted timestamp without any timezone offset information.

The computerTime field encodes the local time at upload with no timezone offset information since we are storing timezone separately. We store this field in order to be able to audit and/or detect the correspondence between the user's browser time and the timezone they selected at the time of upload. If the user selected the timezone that was actually in effect for their browser at the time of upload, then applying the stored timezone to the UTC Zulu time field will match computerTime. If, on the other hand, the user selected a different timezone from that effective in their browser at the time of upload, applying the timezone to time will not match computerTime.

There are some use cases when it is perfectly justified to select a timezone that does not reflect the browser's current timezone. For example, some insulin pump users do not change the time on their devices when traveling for short periods of time across many timezones, but when uploading a device a user should always choose the timezone that aligns with the most recent data on the device and thus that will not match the local browser timezone.

conversionOffsetinteger(int64)(Conversion Offset)

Conversion offset, expressed as milliseconds.

Example: 0
createdTimestring(date-time)(Date/Time)

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
createdUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

dataSetTypestring(Data Set Type)
Enum"continuous""normal"
Example: "continuous"
deduplicatorobject(Deduplicator Descriptor)
deletedTimestring(date-time)(Date/Time)

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
deletedUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

deviceIdstring(Device ID)non-empty

Globally unique to device and repeatable with each upload, e.g. device make and model with serial number

Example: "MMT-1711:12345678"
deviceManufacturersArray of strings(Device Manufacturers)

An array of string tags indicating the manufacturer(s) of the device.

In order to avoid confusion resulting from referring to a single manufacturer with more than one name—for example, using both 'Minimed' and 'Medtronic' interchangeably—we restrict the set of strings used to refer to manufacturers to the set listed above and enforce exact string matches (including casing).

deviceManufacturers is an array of one or more string "tags" because there are devices resulting from a collaboration between more than one manufacturer, such as the Tandem G4 insulin pump with CGM integration (a collaboration between Tandem and Dexcom).

Example: ["DeviceCo"]
deviceModelstring(Device Model Name)non-empty

A string identifying the model of the device.

The deviceModel is a non-empty string that encodes the model of device. We endeavor to match each manufacturer's standard for how they represent model name in terms of casing, whether parts of the name are represented as one word or two, etc.

Example: "Devicey McDeviceface"
deviceSerialNumberstring(Device Serial Number)non-empty

A string encoding the device's serial number.

The deviceSerialNumber is a string that encodes the serial number of the device. Note that even if a manufacturer only uses digits in its serial numbers, the SN should be stored as a string regardless.

Uniquely of string fields in the Tidepool device data models, deviceSerialNumber may be an empty string. This is essentially a compromise: having the device serial number is extremely important (especially for e.g., clinical studies) but in 2016 we came across our first case where we cannot recover the serial number of the device that generated the data: Dexcom G5 data uploaded to Tidepool through Apple iOS's HealthKit integration.

Example: "B97B6D59"
deviceTagsArray of strings(Device Tags)non-empty

An array of string tags indicating the function(s) of the device.

The deviceTags array should be fairly self-explanatory as an array of tags indicating the function(s) of a particular device. For example, the Insulet OmniPod insulin delivery system has the tags bgm and insulin-pump since the PDM is both an insulin pump controller and includes a built-in blood glucose monitor.

Items Enum"bgm""cgm""insulin-pump""fgm""pen""manual"
deviceTimestring(Date/Time without Timezone)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

RFC 3339 / ISO 8601 timestamp without timezone information

Example: "2017-02-06T02:37:46"
idstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...
Example: "ce8cc5f7595575945f91fc6710db6fef"
modifiedTimestring(date-time)(Date/Time)

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
modifiedUserIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-only

String representation of a Tidepool User ID. Old style IDs are 10-digit strings consisting of only hexadeximcal digits. New style IDs are 36-digit UUID v4

payloadobject(Payload)

Grab bag field for data that isn't yet part of the data model. The maximum size is 4K bytes.

sourcestring
timestring(date-time)(Date/Time)

RFC 3339 / ISO 8601 timestamp with timezone information

Example: "2017-02-06T02:37:46Z"
timeProcessingstring(Time Processing)

A string indicating what variety of processing was used to create the time and related fields such as timezoneOffset on data in this upload.

For data auditing purposes, we store a string encoding the type of algorithm used to generate the time, timezoneOffset, and other related fields from the local deviceTime. At present, there are only three options for this value:

  • none for data sources that already include a UTC-anchored time value. At present, the only data source for which this is true is Dexcom G5 or Dexcom G6 data coming through Apple's iOS HealthKit integration.
  • across-the-board-timezone for devices (all BGMs, for example) that cannot have their deviceTime values "bootstrapped" to a UTC time value; in such cases, we apply a single user-selected timezone to every deviceTime "across the board" to generate the time value.
  • utc-bootstrapping for devices (most insulin pumps and CGMs) where we use a combination of the user-selected timezone at time of upload, the most recent timestamp on device, and the history of display time changes on the device to infer the correct time value for each record.
Enum"none""across-the-board-timezone""utc-bootstrapping"
Example: "utc-bootstrapping"
timezonestring(Time Zone)

A string timezone name from the IANA timezone database

Example: "Europe/London"
timezoneOffsetinteger(int32)(Time Zone offset)[ -10080 .. 10080 ]

Time zone offset, expressed as positive or negative number of minutes from UTC.

Example: -420
typestring
Value"upload"
Example: "upload"
versionstring(Semantic Version Number)>= 5 characters^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...

Semantic Version Number 2.0.0. Regex from their site.

Example: "2.36.1"
uploadIdstring(Upload ID)[ 17 .. 32 ] characters^([0-9a-f]{32}|upid_[0-9a-f]{12})$

An upload identifier; this field should be the uploadId of the corresponding upload record

Example: "0d92d5c1c22117a18f3620b9e24d3c06"
guidstringDeprecated

A string ID. Added to each event during data processing in the Tidepool Uploader or upon ingestion by the platform data ingestion service.

Response
application/json
{
  "type": "upload",
  "client": {
    "name": "com.devicecorp.tidepooluploader",
    "version": "0.100.0"
  },
  "dataSetType": "normal",
  "deduplicator": {
    "name": "org.tidepool.deduplicator.device.deactivate.hash",
    "version": "1.2.3"
  },
  "deviceManufacturers": [
    "DeviceCorp"
  ],
  "deviceModel": "Devicey McDeviceface",
  "deviceSerialNumber": "B97B6D59",
  "deviceTags": [
    "bgm",
    "cgm",
    "insulin-pump"
  ],
  "timeProcessing": "none",
  "timezone": "Europe/London",
  "clockDriftOffset": 0,
  "conversionOffset": 0,
  "deviceId": "DevId0987654321",
  "deviceTime": "2016-06-27T18:09:55",
  "time": "2016-06-28T01:09:55.132Z",
  "timezoneOffset": -420
}

Delete Data Set

Request

Deletes an entire dataset specified by the dataSetId.

Security
sessionToken
Path
dataSetIdstring(Data Set ID)[ 17 .. 37 ] characters^(upid_[0-9a-f]{12}|upid_[0-9a-f]{32}|[0-9a-f...required

Data Set ID

Example: ce8cc5f7595575945f91fc6710db6fef
curl -i -X DELETE \
  https://tidepool.redocly.app/_mock/reference/data.v1/v1/data_sets/ce8cc5f7595575945f91fc6710db6fef \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/json
object
Response
application/json
{}