# Chart notes

> The API operations about chart notes, each with its input, its output and an example.

The operations about chart notes. Each one is a `POST` with a JSON object as its body: [Making a request](/docs/api#start) has the rules they share.

## Create chart note

`POST /api/v1/notes.create` · Write

Pins a short note to a day on the main chart of one site, where everyone who opens the dashboard sees it. Use it to record what happened on that day: a release, a campaign, an outage. A date that is not a real day answers 400 invalid. A day holds at most 5 notes and a site at most 500 (409 limit_reached). Every call adds a note, also with the same text. Needs a token with the Write permission.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |
| `date` | string | required | The day the note is pinned to, YYYY-MM-DD in the site's time zone. It must be a real calendar day. |
| `color` | "blue" \| "green" \| "amber" \| "red" \| "purple" \| "grey" | required | The colour of the marker on the chart: blue, green, amber, red, purple or grey. |
| `label` | string, 1 to 60 characters | required | The text of the note, 1 to 60 characters. Say what happened, for example "Launched new pricing page". |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The note id. Pass it to notes.update as id. |
| `date` | string | always | The day the note is pinned to, YYYY-MM-DD in the site's time zone. |
| `color` | "blue" \| "green" \| "amber" \| "red" \| "purple" \| "grey" | always | The colour of the marker on the chart. |
| `label` | string | always | The text of the note. |
| `createdBy` | string | always | Always empty for a token: who wrote a note is shown to signed-in members only. |
| `createdAt` | number | always | When the note was created, milliseconds since 1970 UTC. |
| `updatedAt` | number | always | When the note was last changed, milliseconds since 1970 UTC. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/notes.create \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","date":"2026-10-01","color":"blue","label":"Launch day"}'
```

**CLI**

```bash
clearsaga notes create --input '{"siteId":"site_abc123def456","date":"2026-10-01","color":"blue","label":"Launch day"}'
```

**MCP**

```text
Tool: notes_create
Arguments: {"siteId":"site_abc123def456","date":"2026-10-01","color":"blue","label":"Launch day"}
```

Run `clearsaga help notes create` for one flag per field.

## Delete chart note

`POST /api/v1/notes.delete` · Write

Removes a chart note from one site for good, so its marker leaves the main chart for everyone who opens the dashboard. This cannot be undone. To correct a note and keep it, call notes.update instead. The id comes from notes.list. Only the note goes: the numbers on the chart are not touched. Who wrote the note makes no difference, so this also removes one a person added in the dashboard. An id the site does not have is not an error: the answer says deleted false and nothing was changed, so sending the same call twice is safe. Needs a token with the Write permission.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |
| `id` | string, at least 1 characters | required | The id of the note to remove, from notes.list. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The id that was sent. |
| `deleted` | boolean | always | true when the chart note was there and this call removed it. false when the site has no chart note with that id, because it was removed before or the id is wrong: nothing was changed, and that is not an error. |
| `date` | string \| null | always | The day the note was pinned to, YYYY-MM-DD in the site's time zone. Null when deleted is false. |
| `label` | string \| null | always | The text the note had, so it is clear what was removed. Null when deleted is false. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/notes.delete \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"NOTE_ID"}'
```

**CLI**

```bash
clearsaga notes delete --input '{"siteId":"site_abc123def456","id":"NOTE_ID"}'
```

**MCP**

```text
Tool: notes_delete
Arguments: {"siteId":"site_abc123def456","id":"NOTE_ID"}
```

Run `clearsaga help notes delete` for one flag per field.

## List chart notes

`POST /api/v1/notes.list` · Read

The chart notes of one site whose day lies between two dates, both included, oldest day first. A note is a short dated remark on the main chart, such as a launch or a campaign start, that explains a change in the numbers. Get the siteId from sites.list first. from and to are days in the site's time zone and are both required; there is no range token, no comparison and no filter here. The whole span comes at once, without paging (a site holds at most 500 notes). Keeps working while the workspace is locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |
| `from` | string | required | First day of the span, YYYY-MM-DD in the site's time zone. |
| `to` | string | required | Last day of the span, inclusive, YYYY-MM-DD in the site's time zone. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `rows` | array of object | always | The notes whose day lies in the span, oldest day first: id, date (YYYY-MM-DD), color, label, and createdAt and updatedAt in milliseconds since 1970 UTC. createdBy is always empty for a token. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/notes.list \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","from":"2026-10-01","to":"2026-10-01"}'
```

**CLI**

```bash
clearsaga notes list --input '{"siteId":"site_abc123def456","from":"2026-10-01","to":"2026-10-01"}'
```

**MCP**

```text
Tool: notes_list
Arguments: {"siteId":"site_abc123def456","from":"2026-10-01","to":"2026-10-01"}
```

Run `clearsaga help notes list` for one flag per field.

## Update chart note

`POST /api/v1/notes.update` · Write

Replaces the day, the colour and the text of a chart note. Send all three: a field cannot be left out to keep it. The id comes from notes.list or notes.create. An unknown id answers 404, a date that is not a real day answers 400 invalid, and moving a note to a day that already holds 5 notes answers 409 limit_reached. Sending the same input twice leaves the note as it is. Needs a token with the Write permission.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string | required | The site id, from sites.list. |
| `id` | string, at least 1 characters | required | The id of the note to change, from notes.list. |
| `date` | string | required | The day the note is pinned to, YYYY-MM-DD in the site's time zone. It must be a real calendar day. |
| `color` | "blue" \| "green" \| "amber" \| "red" \| "purple" \| "grey" | required | The colour of the marker on the chart: blue, green, amber, red, purple or grey. |
| `label` | string, 1 to 60 characters | required | The text of the note, 1 to 60 characters. Say what happened, for example "Launched new pricing page". |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The note id. Pass it to notes.update as id. |
| `date` | string | always | The day the note is pinned to, YYYY-MM-DD in the site's time zone. |
| `color` | "blue" \| "green" \| "amber" \| "red" \| "purple" \| "grey" | always | The colour of the marker on the chart. |
| `label` | string | always | The text of the note. |
| `createdBy` | string | always | Always empty for a token: who wrote a note is shown to signed-in members only. |
| `createdAt` | number | always | When the note was created, milliseconds since 1970 UTC. |
| `updatedAt` | number | always | When the note was last changed, milliseconds since 1970 UTC. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/notes.update \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"NOTE_ID","date":"2026-10-01","color":"blue","label":"Launch day"}'
```

**CLI**

```bash
clearsaga notes update --input '{"siteId":"site_abc123def456","id":"NOTE_ID","date":"2026-10-01","color":"blue","label":"Launch day"}'
```

**MCP**

```text
Tool: notes_update
Arguments: {"siteId":"site_abc123def456","id":"NOTE_ID","date":"2026-10-01","color":"blue","label":"Launch day"}
```

Run `clearsaga help notes update` for one flag per field.