---
title: "Create annotation"
method: POST
path: "/api/v1/annotations"
tags: ["Annotations"]
---

# Create annotation

`POST /api/v1/annotations`

Create a chart annotation.

## Request body

- AnnotationCreateRequest
  - `name` string, required — Annotation name.
  - `description` string — Annotation description text in Markdown format.
  - `color` string — Color to be used in charts.
  - `attrs` object — Key-value metadata.
  - `fingerprint` string — Unique string used for deduplication.
  - `time` string, date-time — Overrides annotation time in RFC3339 format.
  - `closeAlerts` CloseAlertsParams — Optional directive to close matching open alerts when the annotation is created. Alerts whose type matches and whose attributes contain all key/value pairs in attrs are closed.
    - `type` 'error' | 'metric', required — Alert type to close.
    - `attrs` object — Attribute key/value pairs that an alert must match to be closed.

## Response `200`

Annotation created.

## Other responses

- `400` — Invalid request
- `401` — Authentication required
- `403` — Insufficient permissions
- `500` — Internal server error

---

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