## Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

Requests go to `https://amplitude.com` (default) or `https://analytics.eu.amplitude.com` (EU). The `https://analytics.amplitude.com` hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not `analytics.amplitude.com`.

| Data residency | Base URL                             |
| -------------- | ------------------------------------ |
| Default        | `https://amplitude.com`              |
| EU             | `https://analytics.eu.amplitude.com` |

## Annotation categories

Manage annotation categories to organize your annotations. Create categories, update their names, and assign them to annotations.

### Create an annotation category

{% code-group %}
```bash cURL
curl --location --request POST 'https://amplitude.com/api/3/annotation-categories' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Releases"
}'
```

```bash HTTP
POST /api/3/annotation-categories HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Content-Type: application/json

{
  "category": "Releases"
}
```
{% /code-group %}

#### Body parameters

| Parameter  | Description                                 |
| ---------- | ------------------------------------------- |
| `category` | Required. String. The name of the category. |

#### Response

```json
{
  "data": {
    "id": 6789,
    "name": "Releases"
  }
}
```

#### Error responses

- `400` - Invalid field
- `409` - Category already exists

### Get all annotation categories

{% code-group %}
```bash cURL
curl --location --request GET 'https://amplitude.com/api/3/annotation-categories' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
GET /api/3/annotation-categories HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Query parameters

| Parameter  | Description                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| `category` | Optional. String. If specified, returns only the specified category. Otherwise, returns all categories. |

#### Response

```json
{
  "data": [
    {
      "id": 12345,
      "name": "Alerts"
    },
    {
      "id": 6789,
      "name": "Releases"
    }
  ]
}
```

#### Error responses

- `400` - Invalid category
- `404` - Category not found

### Get an annotation category by ID

{% code-group %}
```bash cURL
curl --location --request GET 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
GET /api/3/annotation-categories/:category_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Path parameters

| Parameter     | Description                                |
| ------------- | ------------------------------------------ |
| `category_id` | Required. Integer. The ID of the category. |

#### Response

```json
{
  "data": {
    "id": 12345,
    "name": "Alerts"
  }
}
```

#### Error responses

- `400` - Invalid category ID
- `404` - Category not found

### Update an annotation category

{% code-group %}
```bash cURL
curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Updated Category Name"
}'
```

```bash HTTP
PUT /api/3/annotation-categories/:category_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Content-Type: application/json

{
  "category": "Updated Category Name"
}
```
{% /code-group %}

#### Path parameters

| Parameter     | Description                                          |
| ------------- | ---------------------------------------------------- |
| `category_id` | Required. Integer. The ID of the category to update. |

#### Body parameters

| Parameter  | Description                                     |
| ---------- | ----------------------------------------------- |
| `category` | Required. String. The new name of the category. |

#### Response

```json
{
  "data": {
    "id": 569,
    "category": "Updated category name"
  }
}
```

#### Error responses

- `400` - Invalid category ID
- `404` - Category not found
- `409` - Category already exists

### Delete an annotation category

{% code-group %}
```bash cURL
curl --location --request DELETE 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
DELETE /api/3/annotation-categories/:category_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Path parameters

| Parameter     | Description                                          |
| ------------- | ---------------------------------------------------- |
| `category_id` | Required. Integer. The ID of the category to delete. |

#### Response

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

#### Error responses

- `400` - Invalid category ID
- `404` - Category not found

### Bulk update annotation categories

Assign a category to multiple annotations at once.

{% code-group %}
```bash cURL
curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/bulk/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "annotation_ids": [12345, 67890, 11111]
}'
```

```bash HTTP
PUT /api/3/annotation-categories/bulk/:category_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Content-Type: application/json

{
  "annotation_ids": [12345, 67890, 11111]
}
```
{% /code-group %}

#### Path parameters

| Parameter     | Description                                          |
| ------------- | ---------------------------------------------------- |
| `category_id` | Required. Integer. The ID of the category to assign. |

#### Body parameters

| Parameter        | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `annotation_ids` | Required. Array. A list of annotation IDs to update. |

#### Response

```json
{
    "data": [
        {
            "id": 12345,
            "start": "2025-12-18T15:00:00+00:00",
            "label": "test",
            "details": null,
            "category": {
                "id": 12345,
                "category": "Alerts"
            },
            "end": null,
            "chart_id": null
        },
        …
    ]
}
```

#### Error responses

- `400` - Invalid category ID
- `400` - Invalid annotation IDs
- `400` - One or more invalid annotation ID
- `404` - Category not found

## Annotations

Create, retrieve, update, and delete chart annotations. Annotations can span single dates or time ranges with hourly granularity.

### Create an annotation

{% code-group %}
```bash cURL
curl --location --request POST 'https://amplitude.com/api/3/annotations' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Feature X Release",
  "start": "2025-11-01T07:00:00+00:00",
  "category": "Releases",
  "chart_id": "abc123",
  "details": "This marks the release of feature X",
  "end": "2025-11-10T07:00:00+01:00"
}'
```

```bash HTTP
POST /api/3/annotations HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Content-Type: application/json

{
  "label": "Feature X Release",
  "start": "2025-11-01T07:00:00+00:00",
  "category": "Releases",
  "chart_id": "abc123",
  "details": "This marks the release of feature X",
  "end": "2025-11-10T07:00:00+01:00"
}
```
{% /code-group %}

#### Body parameters

| Parameter  | Description                                                                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`    | Required. String. The title of your annotation.                                                                                                                             |
| `start`    | Required. String. Timestamp corresponding to the start of this annotation in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). For example: `"2025-11-01T07:00:00+00:00"`.           |
| `category` | Optional. String. The name of the category that the annotation belongs to.                                                                                                  |
| `chart_id` | Optional. String. The ID of the chart (found in the URL) to annotate. If you don't include `chart_id`, the annotation is global and appears on all charts for your project. |
| `details`  | Optional. String. Details for the annotation.                                                                                                                               |
| `end`      | Optional. String. Timestamp corresponding to the end of this annotation in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). For example: `"2025-11-10T07:00:00+01:00"`.             |

#### Response

```json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}
```

#### Error responses

- `400` - Invalid field
- `404` - Category not found

### Get all annotations

Retrieves all chart annotations in your project. Supports filtering by category, chart, and date range.

{% code-group %}
```bash cURL
curl --location --request GET 'https://amplitude.com/api/3/annotations?category=Releases&start=2025-11-01T07:00:00+00:00&end=2025-11-30T07:00:00+00:00' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
GET /api/3/annotations?category=Releases&start=2025-11-01T07:00:00+00:00&end=2025-11-30T07:00:00+00:00 HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Query parameters

| Parameter  | Description                                                                                                                                                                                                                                                          |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | Optional. String. If specified, only returns annotations in this category. Doesn't combine with `chart_id` filter.                                                                                                                                                   |
| `chart_id` | Optional. String. If specified, only returns annotations that show on this chart. Doesn't combine with `category` filter.                                                                                                                                            |
| `start`    | Optional. String. If specified, only returns annotations that occur after `start` in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). For example: `"2025-11-10T07:00:00+01:00"`.                                                                                            |
| `end`      | Optional. String. If specified, only returns annotations that occur before `end` in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). If the annotation spans a date range, the annotation's end date must be before `end` input. For example: `"2025-11-10T07:00:00+01:00"`. |

#### Response

```json
{
  "data": [
    {
      "id": 12345,
      "start": "2025-11-01T07:00:00+00:00",
      "details": "This marks the release of feature X",
      "category": {
        "id": 45678,
        "name": "Releases"
      },
      "end": "2025-11-10T07:00:00+01:00",
      "label": "Feature X Release",
      "chart_id": null
    }
  ]
}
```

#### Error responses

- `400` - Invalid request
- `409` - Conflict

### Get a single annotation

Retrieves a single chart annotation by ID.

{% code-group %}
```bash cURL
curl --location --request GET 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
GET /api/3/annotations/:annotation_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Path parameters

| Parameter       | Description                                              |
| --------------- | -------------------------------------------------------- |
| `annotation_id` | Required. Integer. The ID of the annotation to retrieve. |

#### Response

```json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}
```

#### Error responses

- `400` - Invalid annotation ID
- `404` - Annotation not found

### Update an annotation

Updates a specific annotation. Supports partial updates. Only the fields you specify in the request body are updated.

{% code-group %}
```bash cURL
curl --location --request PUT 'https://amplitude.com/api/3/annotations/:annotation_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Updated Feature X Release",
  "end": "2025-11-15T07:00:00+01:00"
}'
```

```bash HTTP
PUT /api/3/annotations/:annotation_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
Content-Type: application/json

{
  "label": "Updated Feature X Release",
  "end": "2025-11-15T07:00:00+01:00"
}
```
{% /code-group %}

#### Path parameters

| Parameter       | Description                                            |
| --------------- | ------------------------------------------------------ |
| `annotation_id` | Required. Integer. The ID of the annotation to update. |

#### Body parameters

| Parameter  | Description                                                                                                                                                                                                                                                                       |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`    | Optional. String. The title of your annotation.                                                                                                                                                                                                                                   |
| `start`    | Optional. String. Timestamp corresponding to the start of this annotation in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). For example: `"2025-11-01T07:00:00+00:00"`.                                                                                                                 |
| `category` | Optional. String. The name of the category that the annotation belongs to.                                                                                                                                                                                                        |
| `chart_id` | Optional. String. The ID of the chart (found in the URL) to annotate. If you don't include `chart_id`, the annotation is global and appears on all charts for your project. Set to `null` to remove the association to a specific chart and make the annotation visible globally. |
| `details`  | Optional. String. Details for the annotation.                                                                                                                                                                                                                                     |
| `end`      | Optional. String. Timestamp corresponding to the end of this annotation in ISO 8601 format (`YYYY-MM-DDThh:mmTZD`). For example: `"2025-11-10T07:00:00+01:00"`. Set to `null` to remove the end time.                                                                             |

#### Response

```json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-15T07:00:00+01:00",
    "label": "Updated Feature X Release",
    "chart_id": null
  }
}
```

#### Error responses

- `400` - Invalid field
- `404` - Annotation not found
- `404` - Category not found

### Delete an annotation

{% code-group %}
```bash cURL
curl --location --request DELETE 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'
```

```bash HTTP
DELETE /api/3/annotations/:annotation_id HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded
```
{% /code-group %}

#### Path parameters

| Parameter       | Description                                            |
| --------------- | ------------------------------------------------------ |
| `annotation_id` | Required. Integer. The ID of the annotation to delete. |

#### Response

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

#### Error responses

- `400` - Invalid annotation ID
- `404` - Annotation not found