Sign in
Web Analytics

Create an annotation

Creates a manual annotation. Requires the web_analytics write permission.

source is always stored as manual and source_id is always empty: only the platform writes automatic rows, so there is no way to attach a caller-supplied key to one. This endpoint is therefore not idempotent — a retried call (a CI job re-running a deploy marker, for instance) writes a second annotation. De-duplicate on the caller's side, or delete the extra row.

Omitted color and timezone are filled in server-side: the default colour, and the workspace timezone falling back to UTC.

post/api/annotations.create

Request body

workspace_idstring required
annotated_atstring date-time required

The moment to mark, as an RFC3339 instant.

timezonestring

IANA timezone the moment was entered in, kept for display. Defaults to the workspace timezone, then to UTC.

titlestring required
descriptionstring
colorstring
source'manual'

Only manual is accepted. Sending broadcast is rejected rather than quietly downgraded: it would be claiming the slot of an automatic row.

Example request

{
  "workspace_id": "ws_1234567890",
  "annotated_at": "2026-08-15T09:00:00Z",
  "timezone": "Asia/Tokyo",
  "title": "Pricing page redesign",
  "description": "Rolled out to all visitors after the A/B test.",
  "color": "#3b82f6"
}

Response

Annotation created

Example response

{
  "annotation": {
    "id": "3f2504e04f8911d39a0c0305e82c3301",
    "annotated_at": "2026-08-15T09:00:00Z",
    "timezone": "Asia/Tokyo",
    "title": "Pricing page redesign",
    "description": "Rolled out to all visitors after the A/B test.",
    "color": "#3b82f6",
    "source": "manual",
    "source_id": "bcast_1234567890"
  }
}

Changes