# Notes

> Read and add the notes your team keeps on a client, private or shared with them.

Source: https://hubfit.com/developers/api/notes


Notes your team keeps on a client. A private note is seen only by your team; a shared one also shows in the client's app.

Endpoints:

- `GET /v1/clients/{clientId}/notes`: [List a client's notes](https://hubfit.com/developers/api/notes#list-client-notes)
- `POST /v1/clients/{clientId}/notes`: [Add a note to a client](https://hubfit.com/developers/api/notes#create-client-note)

## Note object

### Attributes

- `id` (string): Its unique ID.
- `title` (string): The note's heading. Empty if it has none.
- `text` (string)
- `visibility` (enum): `private` if only your team sees the note. `shared` if the client sees it in their app too; adding a shared note sends them a push notification with its text. One of `private`, `shared`.
- `createdAt` (timestamp): When it was created.

### Example

```json
{
  "id": "6ad6af897f67308a7f68c38b",
  "title": "Training days",
  "text": "Moving to 4 sessions a week from November. Prefers mornings.",
  "visibility": "private",
  "createdAt": "2026-03-02T15:04:11.000Z"
}
```

## List a client's notes

`GET https://api.hubfit.com/v1/clients/{clientId}/notes`

The notes your team keeps on the client, newest first, private and shared alike. Requires `clients:read`.

### Path parameters

- `clientId` (string, required): The client's `id`.

### Query parameters

- `limit` (integer): How many notes a page holds. 10 unless you ask for more, and at most 50, fewer than other lists, as a note can be 5,000 characters. Default `10`.
- `cursor` (string): The `nextCursor` from the previous page.

### Returns

A page of the client's notes.

### Example request

cURL:

```bash
curl https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes \
  -H "Authorization: Bearer $HUBFIT_API_KEY"
```

Node.js:

```javascript
const response = await fetch("https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes", {
  headers: {
    Authorization: `Bearer ${process.env.HUBFIT_API_KEY}`,
  },
});

const { data, nextCursor } = await response.json();
```

Python:

```python
import os
import requests

response = requests.get(
    "https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes",
    headers={"Authorization": f"Bearer {os.environ['HUBFIT_API_KEY']}"},
)

page = response.json()
data, next_cursor = page["data"], page["nextCursor"]
```

### Example response (200 OK)

```json
{
  "data": [
    {
      "id": "6ad6af897f67308a7f68c38b",
      "title": "Training days",
      "text": "Moving to 4 sessions a week from November. Prefers mornings.",
      "visibility": "private",
      "createdAt": "2026-03-02T15:04:11.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjZhZDZhZjNmMjljNTk3ZjE1In0",
  "totalCount": 48
}
```

## Add a note to a client

`POST https://api.hubfit.com/v1/clients/{clientId}/notes`

Adds a note to the client, as adding one in the app does. A `private` note is seen only by your team. A `shared` one shows in the client's app straight away and sends them a push notification with its text. Each call adds another note, so send an `Idempotency-Key` to retry safely. A client holds at most 100 notes; past that it's `409 note_limit_reached`. Requires `clients:write`.

### Headers

- `Idempotency-Key` (string): Any unique string, such as a UUID, up to 255 characters. Retrying with the same key within 24 hours returns the first response instead of repeating the write. See [Idempotency](https://hubfit.com/developers/idempotency).

### Path parameters

- `clientId` (string, required): The client's `id`.

### Body parameters

- `title` (string): A heading for the note.
- `text` (string, required): The note. Can't be blank.
- `visibility` (enum, required): `private` if only your team sees the note. `shared` if the client sees it in their app too; adding a shared note sends them a push notification with its text. One of `private`, `shared`.

### Returns

The new note.

### Example request

cURL:

```bash
curl -X POST https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes \
  -H "Authorization: Bearer $HUBFIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Training days",
    "text": "Moving to 4 sessions a week from November. Prefers mornings.",
    "visibility": "private"
  }'
```

Node.js:

```javascript
const response = await fetch("https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUBFIT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "Training days",
    text: "Moving to 4 sessions a week from November. Prefers mornings.",
    visibility: "private",
  }),
});

const { data } = await response.json();
```

Python:

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.hubfit.com/v1/clients/6ad6af41d3199442d31b2743/notes",
    headers={"Authorization": f"Bearer {os.environ['HUBFIT_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "title": "Training days",
        "text": "Moving to 4 sessions a week from November. Prefers mornings.",
        "visibility": "private",
    },
)

data = response.json()["data"]
```

### Example response (201 Created)

```json
{
  "data": {
    "id": "6ad6af897f67308a7f68c38b",
    "title": "Training days",
    "text": "Moving to 4 sessions a week from November. Prefers mornings.",
    "visibility": "private",
    "createdAt": "2026-03-02T15:04:11.000Z"
  }
}
```