---
title: "Create an annotation"
method: POST
path: "/api/v2/annotation"
tags: ["Annotations"]
---

# Create an annotation

`POST /api/v2/annotation`

Creates a new annotation on a dashboard or notebook page.
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`).

## Request body

- AnnotationCreateRequest — Request body for creating 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
- `429` — Too many requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)