# Create a chart comment

Pins a comment to a point in time on a chart, the same comment you get by clicking the chart in the Better Stack interface. Use it to mark releases, deployments, and incidents on your charts from your own scripts.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/dashboards/{dashboard_id}/charts/{chart_id}/comments"
method = "POST"

[[path_param]]
name = "dashboard_id"
description = "The unique identifier of the dashboard."
required = true
type = "integer"

[[path_param]]
name = "chart_id"
description = "The unique identifier of the chart. Only a line chart can show comments."
required = true
type = "integer"

[[body_param]]
name = "dt"
description = "The point on the chart's time axis to pin the comment to, as a datetime such as `2026-08-17T12:34:56.789Z`. A datetime without a zone offset is read as UTC."
required = true
type = "string"

[[body_param]]
name = "content"
description = "The content of the comment. [Markdown](https://www.markdownguide.org/basic-syntax/) is supported for formatting."
required = true
type = "string"

[[body_param]]
name = "user_email"
description = "E-mail of a team member to tag in the comment. The mention goes in front of your content, and that team member is notified."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = "The comment was created successfully."
body = '''
{
  "data": {
    "id": "1441",
    "type": "chart_comment",
    "attributes": {
      "chart_id": 18718,
      "content": "Deployed v2.1.0",
      "created_at": "2026-08-17T12:52:21.837Z",
      "updated_at": "2026-08-17T12:52:21.837Z",
      "dt": "2026-08-17T12:34:56.789Z",
      "plaintext_content": "Deployed v2.1.0",
      "api_authored": true
    }
  }
}
'''

[[response]]
status = 422
description = "`dt` or `content` is missing, `dt` is not a datetime, `user_email` is not a member of the team the dashboard belongs to, or the chart cannot show comments."

[[response]]
status = 404
description = "A dashboard or chart with the specified ID was not found."
[/responses]

## Example request

```shell
[label cURL]
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/1234/charts/18718/comments \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "dt": "2026-08-17T12:34:56.789Z",
    "content": "Deployed v2.1.0",
    "user_email": "sarah@example.com"
  }'
```

## Chart types that show comments

Comments are drawn on the time axis of a **line chart**. Pinning one to any other chart type returns `422` with a `chart_type` error, because the comment would never be visible.

## Tag a team member

`user_email` has to belong to a member of the team the dashboard belongs to. The mention goes in front of your content, so the comment above shows as `@Sarah Connor Deployed v2.1.0` on the chart, and Sarah is notified exactly as if somebody had tagged her by hand.

Send `user_email` on create only. A mention is part of the comment content, so to change one, send the whole `content` you want to [Update a chart comment](https://betterstack.com/docs/logs/api/chart-comments/update/).

## Who the comment is from

A comment created with an API token has no author. It shows as **Comment added using API** on the chart, its `api_authored` attribute is `true`, and it notifies only the team members it tags. Marking every deploy on a chart therefore stays quiet.

A comment created with an OAuth token is attributed to the team member that token belongs to, and notifies the whole team just like a comment written in the Better Stack interface.