List Annotations

Get all annotations for a site.

List Annotations

Returns all annotations for a site, ordered by date. Annotations are markers on the analytics timeline (e.g. deployments, marketing launches).

Endpoint

GET /api/v1/organizations/:orgId/sites/:siteId/annotations

Response fields

Returns an array of annotation entries:

Field	Type	Description
`id`	`string`	Annotation ID
`label`	`string`	Annotation label
`occurred_at`	`string`	Annotation date (ISO 8601)
`description`	`string`	Optional longer description
`color`	`string`	Marker color
`created_by`	`object`	Author object with `id`, `name`, `email`
`created_at`	`string`	Creation timestamp (ISO 8601)

Example request (cURL)

curl -X GET \
  'https://api.engagetrack.net/api/v1/organizations/{orgId}/sites/{siteId}/annotations' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json'

Success response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "ann_abc123",
      "label": "Launched spring marketing campaign",
      "occurred_at": "2024-02-01T00:00:00Z",
      "description": "Kicked off the spring 2024 campaign across all channels",
      "color": "#4f46e5",
      "created_by": {
        "id": "user_123",
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "created_at": "2024-02-01T09:00:00Z"
    },
    {
      "id": "ann_def456",
      "label": "v2.0 deployed to production",
      "occurred_at": "2024-01-15T00:00:00Z",
      "description": "",
      "color": "#10b981",
      "created_by": {
        "id": "user_456",
        "name": "John Doe",
        "email": "[email protected]"
      },
      "created_at": "2024-01-15T16:30:00Z"
    }
  ]
}