List notes

curl --request GET \
  --url 'https://truestat.io/api/v1/sites/{siteId}/notes' \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": "02eae3c2-3790-4edd-a2ff-577eb2a8b0ba",
      "body": "Deployed v2 — new pricing page",
      "author_id": "734c7de3-58f1-46e6-83d1-2be85466ee70",
      "created_at": "2026-09-16T10:02:11.000Z",
      "updated_at": "2026-09-16T10:02:11.000Z",
      "granularity": "minute",
      "occurred_at": "2026-09-16T10:00:00+00:00"
    }
  ],
  "meta": {
    "page": {
      "limit": 100,
      "offset": 0,
      "has_more": false
    },
    "site_id": "6fed8980-a119-4a9c-a4d4-53e448ef9f9e"
  }
}

Every note on the site, newest first.

The window filters by when things happened

Passing period or from/to narrows the list by occurred_at — when the annotated thing happened — not by when the note was written. That is the same question the chart asks, so a caller drawing annotations alongside a timeseries passes the same window to both.

Without a window you get the most recent notes regardless of date, which is what a caller syncing notes into an external system wants.

author_id can be null

That is not an error. A note outlives the person who wrote it: when somebody leaves the team their notes stay on the chart and the author becomes null.

The field is an id rather than a name — resolving names would mean reading the user table on a path that does not otherwise need it. Match it against your own records, or ignore it.

Reading and writing are separate permissions

This endpoint needs notes:read. A key with only that can list notes and cannot create, edit or delete them — those need notes:write.

Authorizations

Path parameters

Query parameters

Response