Skip to content
Tidepool API/Messages API/
/
Update Message

Messages 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
message.v1.json
message.v1.yaml
Overview
URL

https://support.tidepool.org/

API Support

support@tidepool.org

License

BSD-2-Clause

Languages
Servers
Mock server

https://tidepool.redocly.app/_mock/reference/message.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.

Messages

List, create and manage messages (also known as notes) in the user's account.

All APIs require a valid session token provided via the X-Tidepool-Session-Token header. There is currently no unauthenticated access to messages.

The common API input parameter userId is a Tidepool User ID that identifies the user whose account contains the messages. That user may have shared their account with (=given permission to) other users who can view and manage messages in their account. Therefore, in each API request the user ID identified with the session token must either a) match the userId parameter, or b) the corresponding user must have been granted the note permission to manage messages in the user account identified by userId.

Similarly, in the API responses the groupid field is a Tidepool User ID that identifies the user whose account contains the messages, corresponding to the userId parameter in requests. The userid field identifies the user who actually created the message, corresponding to the user ID encoded within the session token. The message was created by the owner of the account if these two fields match.

Each message has a unique message ID, and the messages can be threaded. A user can create either a new message, or create a reply to another message. Each message contains a parentmessage field that contains the message ID of previous message in the thread. Messages that have no parentmessage field value (i.e. it is null) are top-level messages, that is, the beginning of a message thread.

See the Authorization API for details on how permissions are managed.

Operations

List All Messages

Request

List all messages in the user account identified by userId, optionally within the time range bounded by starttime and/or endtime.

Security
sessionToken
Path
userIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-onlyrequired

Tidepool User ID

Query
starttimestring(date-time)(Date/Time)

Start Time. Start date/time of the range for messages

Example: starttime=2017-02-06T02:37:46Z
endtimestring(date-time)(Date/Time)

End Time. End date/time of the range for messages

Example: endtime=2017-02-06T02:37:46Z
curl -i -X GET \
  'https://tidepool.redocly.app/_mock/reference/message.v1/message/all/{userId}?starttime=2017-02-06T02%3A37%3A46Z&endtime=2017-02-06T02%3A37%3A46Z' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Message list.

Bodyapplication/json
messagesArray of objects(Message)required
messages[].​messageobject
Response
application/json
{
  "messages": [
    { … }
  ]
}

List Top-Level Messages

Request

List only the top-level message threads in the user account identified by userId, optionally within the time range bounded by starttime and/or endtime. Top-level messages are the starting point of each message thread (i.e. parentmessage == null), that is, messages that are not responses to other messages.

Security
sessionToken
Path
userIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-onlyrequired

Tidepool User ID

Query
starttimestring(date-time)(Date/Time)

Start Time. Start date/time of the range for messages

Example: starttime=2017-02-06T02:37:46Z
endtimestring(date-time)(Date/Time)

End Time. End date/time of the range for messages

Example: endtime=2017-02-06T02:37:46Z
curl -i -X GET \
  'https://tidepool.redocly.app/_mock/reference/message.v1/message/notes/{userId}?starttime=2017-02-06T02%3A37%3A46Z&endtime=2017-02-06T02%3A37%3A46Z' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Message list.

Bodyapplication/json
messagesArray of objects(Message)required
messages[].​messageobject
Response
application/json
{
  "messages": [
    { … }
  ]
}

Create New Top-Level Message

Request

Creates a new top-level message (thread) in the account identified by userId. Top-level messages are the starting point of a message thread (i.e. parentmessage == null), that is, not a response to any other message.

Security
sessionToken
Path
userIdstring(Tidepool User ID)^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-...read-onlyrequired

Tidepool User ID

Bodyapplication/json
messageobject
curl -i -X POST \
  'https://tidepool.redocly.app/_mock/reference/message.v1/message/send/{userId}' \
  -H 'Content-Type: application/json' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE' \
  -d '{
    "message": {
      "messagetext": "string",
      "timestamp": "2017-02-06T02:37:46Z",
      "guid": "b9468a76-4afc-4c33-8d1d-1f08324d9160"
    }
  }'

Responses

Message created

Bodyapplication/json
idstring(Message ID)= 24 characters^[0-9a-f]{24}$required
Example: "60e64ddf98b2350011b0f37f"
Response
application/json
{
  "id": "60e64ddf98b2350011b0f37f"
}

Reply to Message

Request

Adds a reply to an existing message identified by messageId.

Security
sessionToken
Path
messageIdstring(Message ID)= 24 characters^[0-9a-f]{24}$required

Message ID

Example: 60e64ddf98b2350011b0f37f
Bodyapplication/json
messageobject
curl -i -X POST \
  https://tidepool.redocly.app/_mock/reference/message.v1/message/reply/60e64ddf98b2350011b0f37f \
  -H 'Content-Type: application/json' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE' \
  -d '{
    "message": {
      "messagetext": "string",
      "timestamp": "2017-02-06T02:37:46Z",
      "guid": "b9468a76-4afc-4c33-8d1d-1f08324d9160"
    }
  }'

Responses

Message created

Bodyapplication/json
idstring(Message ID)= 24 characters^[0-9a-f]{24}$required
Example: "60e64ddf98b2350011b0f37f"
Response
application/json
{
  "id": "60e64ddf98b2350011b0f37f"
}

Get Message by ID

Request

Returns message identified by messageId

Security
sessionToken
Path
messageIdstring(Message ID)= 24 characters^[0-9a-f]{24}$required

Message ID

Example: 60e64ddf98b2350011b0f37f
curl -i -X GET \
  https://tidepool.redocly.app/_mock/reference/message.v1/message/read/60e64ddf98b2350011b0f37f \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Message.

Bodyapplication/json
messageobject
Response
application/json
{
  "message": {
    "id": "60e64ddf98b2350011b0f37f",
    "guid": "b9468a76-4afc-4c33-8d1d-1f08324d9160",
    "parentmessage": "60e64ddf98b2350011b0f37f",
    "userid": "string",
    "groupid": "string",
    "timestamp": "2017-02-06T02:37:46Z",
    "createdtime": "2017-02-06T02:37:46Z",
    "modifiedtime": "2017-02-06T02:37:46Z",
    "messagetext": "I ate a taco with 10g of carbs",
    "user": { … }
  }
}

Get Message Thread by ID

Request

Returns message thread identified by messageId

Security
sessionToken
Path
messageIdstring(Message ID)= 24 characters^[0-9a-f]{24}$required

Message ID

Example: 60e64ddf98b2350011b0f37f
curl -i -X GET \
  https://tidepool.redocly.app/_mock/reference/message.v1/message/thread/60e64ddf98b2350011b0f37f \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Message list.

Bodyapplication/json
messagesArray of objects(Message)required
messages[].​messageobject
Response
application/json
{
  "messages": [
    { … }
  ]
}

Update Message

Request

Updates the message identified by messageId. Either the timestamp or the messagetext field or both must be supplied in the request body. No other fields of the message may be updated. The modifiedtime field of the message will indicate when the message was last modified.

Security
sessionToken
Path
messageIdstring(Message ID)= 24 characters^[0-9a-f]{24}$required

Message ID

Example: 60e64ddf98b2350011b0f37f
Bodyapplication/json
messageobject
Any of:
curl -i -X PUT \
  https://tidepool.redocly.app/_mock/reference/message.v1/message/edit/60e64ddf98b2350011b0f37f \
  -H 'Content-Type: application/json' \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE' \
  -d '{
    "message": {
      "messagetext": "string",
      "timestamp": "2017-02-06T02:37:46Z"
    }
  }'

Responses

Success

Response
No content

Delete Message

Request

Deletes the message identified by messageId.

Security
sessionToken
Path
messageIdstring(Message ID)= 24 characters^[0-9a-f]{24}$required

Message ID

Example: 60e64ddf98b2350011b0f37f
curl -i -X DELETE \
  https://tidepool.redocly.app/_mock/reference/message.v1/message/remove/60e64ddf98b2350011b0f37f \
  -H 'X-Tidepool-Session-Token: YOUR_API_KEY_HERE'

Responses

Success

Response
No content