---
title: "Update an annotation"
method: PUT
path: "/api/v2/annotation/{annotation_id}"
tags: ["Annotations"]
---

# Update an annotation

`PUT /api/v2/annotation/{annotation_id}`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/annotation/{annotation_id}`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

Updates an existing annotation.
Valid `color` values: `gray`, `blue`, `purple`, `green`, `yellow`, `red`.
Valid `type` values: `pointInTime` (marks a single moment) or `timeRegion` (spans a range and requires `end_time`).

## Path parameters

- `annotation_id` string, uuid, required

## Request body

- AnnotationUpdateRequest: Request body for updating an annotation.
  - `data` AnnotationRequestData, required: Data for creating an annotation.
    - `attributes` AnnotationCreateAttributes, required: Attributes for creating or updating an annotation.
      - `color` 'gray' | 'blue' | 'purple' | 'green' | 'yellow' | 'red', required: Color used to render the annotation in the UI.
      - `description` string, required: User-defined text attached to the annotation.
      - `end_time` integer, nullable: End time of the annotation in milliseconds since the Unix epoch. Required for `timeRegion` annotations; omit or set to null for `pointInTime` annotations.
      - `page_id` string, required: ID of the page the annotation belongs to, prefixed with the page type and joined by a colon (for example, `dashboard:abc-def-xyz` or `notebook:1234567890`).
      - `start_time` integer, required: Start time of the annotation in milliseconds since the Unix epoch.
      - `type` 'pointInTime' | 'timeRegion', required: Kind of annotation. `pointInTime` annotations mark a single moment in time, while `timeRegion` annotations span a window of time and require an `end_time`.
      - `widget_ids` string[]: IDs of widgets the annotation is associated with. When empty or omitted, the annotation applies to the whole page.
    - `type` 'annotation', required: Annotation resource type.

## Response `200`

OK

- AnnotationResponse: Response containing a single annotation.
  - `data` AnnotationData, required: A single annotation resource.
    - `attributes` AnnotationAttributes, required: Attributes of an annotation returned in a response.
      - `author_id` string, required: Identifier of the user who created the annotation.
      - `color` 'gray' | 'blue' | 'purple' | 'green' | 'yellow' | 'red', required: Color used to render the annotation in the UI.
      - `created_at` integer, required: Creation time of the annotation in milliseconds since the Unix epoch.
      - `description` string, required: User-defined text attached to the annotation.
      - `end_time` integer, nullable, required: End time of the annotation in milliseconds since the Unix epoch. Null for `pointInTime` annotations.
      - `modified_at` integer, required: Last modification time of the annotation in milliseconds since the Unix epoch.
      - `page_id` string, required: ID of the page the annotation belongs to, prefixed with the page type and joined by a colon (for example, `dashboard:abc-def-xyz` or `notebook:1234567890`).
      - `start_time` integer, required: Start time of the annotation in milliseconds since the Unix epoch.
      - `type` 'pointInTime' | 'timeRegion', required: Kind of annotation. `pointInTime` annotations mark a single moment in time, while `timeRegion` annotations span a window of time and require an `end_time`.
      - `widget_ids` string[]: IDs of widgets the annotation is associated with. When empty or omitted, the annotation applies to the whole page.
    - `id` string, uuid, required: Unique identifier of the annotation.
    - `type` 'annotation', required: Annotation resource type.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `429`: Too many requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)