Notes | TrueStat

A note is the one part of a dashboard nobody can reconstruct from the data.

Six months from now a spike is a mystery unless something written at the time says what happened — and the thing that knows is usually a deploy pipeline, a campaign tool or a release script rather than a person sitting at the dashboard. That is what these endpoints are for.

The four calls

List

GET /sites/{siteId}/notes — most recent first, optionally filtered to a window.

Create

POST /sites/{siteId}/notes — the one a deploy script calls.

Edit

PATCH /sites/{siteId}/notes/{noteId} — the body, and only the body.

Delete

DELETE /sites/{siteId}/notes/{noteId} — irreversible.

Reading needs notes:read; all three writes need notes:write.

From a deploy script

The shape most people want. One call at the end of a release:

curl -X POST "https://truestat.io/api/v1/sites/$SITE_ID/notes" \
  -H "Authorization: Bearer $TRUESTAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"body\": \"Deployed $GIT_SHA\",
    \"occurred_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"granularity\": \"minute\"
  }"

Use minute for anything with a time — a deploy, an incident, a switch thrown. Use date for things that belong to a day: a campaign launch, a price change, a press mention.

The difference is not cosmetic. A date note stays on the day it describes even if the site's timezone changes later; a minute note moves with the clock, as every other timestamp does.

Who a note belongs to

The dashboard shows each note's author and lets that person edit their own.

A key is not a person, so a note written through the API is attributed to whoever created the key. That keeps it editable from the screen and makes it clear who is responsible for it.

The consequence to know about: a key can edit and delete only the notes it wrote. Another person's note answers 403, and so does a note that does not exist — the two are deliberately indistinguishable, so this cannot be used to discover which ids are real.

occurred_at is when the annotated thing happened, not when you called the endpoint. Backfilling last week's release is a normal thing to do.

What you cannot change

Only the body is editable. A note pinned to the wrong moment is deleted and rewritten rather than moved — silently shifting when something happened changes what a past chart meant, and nobody looking at it would know.