annotations

Create, Read, Update and Delete annotations. See docs for more information on annotations.

post/api/projects/{project_id}/annotations/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/annotations/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

idinteger required
contentstring nullable

Annotation text shown on charts to describe the change, release, or incident.

date_markerstring date-time nullable

When this annotation happened (ISO 8601 timestamp). Used to position it on charts.

creation_type'USR' | 'GIT'
  • USR - user
  • GIT - GitHub
dashboard_iteminteger nullable

Optional insight ID to attach this annotation to. Must belong to the current project.

dashboard_idinteger nullable

Optional dashboard ID to attach this annotation to. Must belong to the current project.

dashboard_namestring nullable required
insight_short_idstring nullable required
insight_namestring nullable required
insight_derived_namestring nullable required
created_atstring date-time nullable required
updated_atstring date-time required
deletedboolean

Soft-delete flag. Set to true to hide the annotation, or false to restore it.

scope'dashboard_item' | 'dashboard' | 'project' | 'organization' | 'recording'
  • dashboard_item - insight
  • dashboard - dashboard
  • project - project
  • organization - organization
  • recording - recording
emojistring nullable

Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.

hidden_in_user_interfaceboolean nullable

When true, the annotation is hidden from the PostHog UI (charts and the annotations list) but still readable over the API and MCP. Use for high-frequency markers like deployments that would otherwise crowd the UI. Null (the default) means the annotation is shown.

Response

idinteger required
contentstring nullable

Annotation text shown on charts to describe the change, release, or incident.

date_markerstring date-time nullable

When this annotation happened (ISO 8601 timestamp). Used to position it on charts.

creation_type'USR' | 'GIT'
  • USR - user
  • GIT - GitHub
dashboard_iteminteger nullable

Optional insight ID to attach this annotation to. Must belong to the current project.

dashboard_idinteger nullable

Optional dashboard ID to attach this annotation to. Must belong to the current project.

dashboard_namestring nullable required
insight_short_idstring nullable required
insight_namestring nullable required
insight_derived_namestring nullable required
created_atstring date-time nullable required
updated_atstring date-time required
deletedboolean

Soft-delete flag. Set to true to hide the annotation, or false to restore it.

scope'dashboard_item' | 'dashboard' | 'project' | 'organization' | 'recording'
  • dashboard_item - insight
  • dashboard - dashboard
  • project - project
  • organization - organization
  • recording - recording
emojistring nullable

Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.

hidden_in_user_interfaceboolean nullable

When true, the annotation is hidden from the PostHog UI (charts and the annotations list) but still readable over the API and MCP. Use for high-frequency markers like deployments that would otherwise crowd the UI. Null (the default) means the annotation is shown.

Changes