Skip to content

API reference Chart notes

API reference

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 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 -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"}'

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 -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"}'

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 -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"}'

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 -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"}'

Run clearsaga help notes update for one flag per field.