---
title: Annotations
description: GET/POST/DELETE /v1/annotations - Manage chart annotations
url: https://www.supalytics.co/docs/api/annotations
---



Add, list, and delete annotations to mark important events on your charts (product launches, marketing campaigns, incidents, etc.).

## List Annotations

```
GET https://api.supalytics.co/v1/annotations
```

Returns all annotations for a website within an optional date range.

### Query Parameters

| Parameter    | Type   | Required | Description             |
| ------------ | ------ | -------- | ----------------------- |
| `domain`     | string | Yes      | Site domain to query    |
| `start_date` | string | No       | Start date (YYYY-MM-DD) |
| `end_date`   | string | No       | End date (YYYY-MM-DD)   |

### Response

```json
{
  "data": [
    {
      "id": "abc123",
      "date": "2024-12-15",
      "title": "Product launch",
      "created_by": "user_xxx",
      "created_at": "2024-12-15T10:30:00Z",
      "updated_at": "2024-12-15T10:30:00Z"
    },
    {
      "id": "def456",
      "date": "2024-12-01",
      "title": "Black Friday campaign",
      "created_by": "user_xxx",
      "created_at": "2024-12-01T08:00:00Z",
      "updated_at": "2024-12-01T08:00:00Z"
    }
  ],
  "meta": {
    "domain": "example.com",
    "date_range": ["2024-12-01", "2024-12-31"]
  }
}
```

### Example

```bash
curl "https://api.supalytics.co/v1/annotations?domain=example.com&start_date=2024-12-01&end_date=2024-12-31" \
  -H "Authorization: Bearer sly_xxx..."
```

***

## Create Annotation

```
POST https://api.supalytics.co/v1/annotations
```

Creates a new annotation for a specific date.

### Request Body

| Field    | Type   | Required | Description                          |
| -------- | ------ | -------- | ------------------------------------ |
| `domain` | string | Yes      | Site domain                          |
| `date`   | string | Yes      | Date for the annotation (YYYY-MM-DD) |
| `title`  | string | Yes      | Annotation title (max 250 chars)     |

### Request

```json
{
  "domain": "example.com",
  "date": "2024-12-15",
  "title": "Product launch"
}
```

### Response

```json
{
  "id": "abc123",
  "date": "2024-12-15",
  "title": "Product launch",
  "created_by": "user_xxx",
  "created_at": "2024-12-15T10:30:00Z",
  "updated_at": "2024-12-15T10:30:00Z"
}
```

### Example

```bash
curl -X POST https://api.supalytics.co/v1/annotations \
  -H "Authorization: Bearer sly_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "date": "2024-12-15",
    "title": "Product launch"
  }'
```

***

## Delete Annotation

```
DELETE https://api.supalytics.co/v1/annotations/:id
```

Deletes an annotation by ID.

### Path Parameters

| Parameter | Description   |
| --------- | ------------- |
| `id`      | Annotation ID |

### Query Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `domain`  | string | Yes      | Site domain (for authorization) |

### Response

```json
{
  "success": true
}
```

### Example

```bash
curl -X DELETE "https://api.supalytics.co/v1/annotations/abc123?domain=example.com" \
  -H "Authorization: Bearer sly_xxx..."
```

***

## Authentication

| Endpoint                   | Required Scope    |
| -------------------------- | ----------------- |
| GET /v1/annotations        | `analytics:read`  |
| POST /v1/annotations       | `analytics:write` |
| DELETE /v1/annotations/:id | `analytics:write` |

```
Authorization: Bearer sly_xxx...
```

Both Project API Keys and Personal Access Tokens (PATs) are supported.

## Error Responses

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| 400    | Invalid request (validation error)                       |
| 403    | Access denied (wrong domain or insufficient permissions) |
| 404    | Annotation not found                                     |
| 500    | Server error                                             |

See [Errors](/docs/api/errors) for details.


---

## Other Documentation

- [Autocapture](https://www.supalytics.co/llms/docs/autocapture)
- [Backfill Existing Subscriptions](https://www.supalytics.co/llms/docs/backfill-existing-subscriptions)
- [Block Your Own Traffic](https://www.supalytics.co/llms/docs/block-your-traffic)
- [CLI](https://www.supalytics.co/llms/docs/cli)
- [Custom Events](https://www.supalytics.co/llms/docs/custom-events)
- [Features](https://www.supalytics.co/llms/docs/features)
- [Conversion Funnels](https://www.supalytics.co/llms/docs/funnels)
- [Introduction](https://www.supalytics.co/llms/docs)
- [Install Script](https://www.supalytics.co/llms/docs/install-script)
- [MRR Tracking](https://www.supalytics.co/llms/docs/mrr-tracking)
- [Revenue Attribution](https://www.supalytics.co/llms/docs/revenue-attribution)
- [Agent Skills](https://www.supalytics.co/llms/docs/skills)
- [Tracking Modes](https://www.supalytics.co/llms/docs/tracking-modes)
- [Visitor Journey](https://www.supalytics.co/llms/docs/visitor-journey)
- [Error Codes](https://www.supalytics.co/llms/docs/api/errors)
- [Events (Read)](https://www.supalytics.co/llms/docs/api/events)
- [API Reference](https://www.supalytics.co/llms/docs/api)
- [Journeys](https://www.supalytics.co/llms/docs/api/journeys)
- [Query API](https://www.supalytics.co/llms/docs/api/query)
- [Realtime API](https://www.supalytics.co/llms/docs/api/realtime)
- [Revenue Attribution API](https://www.supalytics.co/llms/docs/api/revenue-attribution)
- [Events (Write)](https://www.supalytics.co/llms/docs/api/server-side-events)