# Messages API

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](../docs/quick-start.md) section.

Version: 1.0
License: BSD-2-Clause

## Servers

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
```

## Security

### sessionToken

Tidepool Session Token

Type: apiKey
In: header
Name: X-Tidepool-Session-Token

## Download OpenAPI description

[Messages API](https://tidepool.redocly.app/_spec/reference/message.v1.yaml)

## 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.

### List All Messages

 - [GET /message/all/{userId}](https://tidepool.redocly.app/reference/message.v1/messages/listallmessages.md): List all messages in the user account identified by , optionally within the time range bounded by  and/or .

### List Top-Level Messages

 - [GET /message/notes/{userId}](https://tidepool.redocly.app/reference/message.v1/messages/listtoplevelmessages.md): List only the top-level message threads in the user account identified by , optionally within the time range bounded by  and/or . Top-level messages are the starting point of each message thread (i.e.  == ), that is, messages that are not responses to other messages.

### Create New Top-Level Message

 - [POST /message/send/{userId}](https://tidepool.redocly.app/reference/message.v1/messages/createmessage.md): Creates a new top-level message (thread) in the account identified by . Top-level messages are the starting point of a message thread (i.e.  == ), that is, not a response to any other message.

### Reply to Message

 - [POST /message/reply/{messageId}](https://tidepool.redocly.app/reference/message.v1/messages/replytomessage.md): Adds a reply to an existing message identified by .

### Get Message by ID

 - [GET /message/read/{messageId}](https://tidepool.redocly.app/reference/message.v1/messages/findmessagebyid.md): Returns message identified by 

### Get Message Thread by ID

 - [GET /message/thread/{messageId}](https://tidepool.redocly.app/reference/message.v1/messages/getmessagethread.md): Returns message thread identified by 

### Update Message

 - [PUT /message/edit/{messageId}](https://tidepool.redocly.app/reference/message.v1/messages/updatemessage.md): Updates the message identified by . Either the  or the  field or both must be supplied in the request body. No other fields of the message may be updated. The  field of the message will indicate when the message was last modified.

### Delete Message

 - [DELETE /message/remove/{messageId}](https://tidepool.redocly.app/reference/message.v1/messages/deletemessage.md): Deletes the message identified by .