Annotations

Last updated:

For instructions on how to authenticate to use this endpoint, see API overview.

Our annotations endpoints allows you to create, update, and fetch annotations from PostHog.

Endpoints

Annotation

GET
/api/annotation

Get a list of your annotations from PostHog.

Query parameters

ParameterType / Valid ValuesDescriptionRequired
scope- "organization"
- "dashboard_item"
Types of annotations to fetch. Annotations with scope organization are available on all charts, whereas dashboard_item annotations are associated with one particular chart.
order- "updated_at"
- "created_at"
- "date_marker"
Property to be used for sorting the annotations in the response. Adding - in front of the value will reverse the order from ascending to descending e.g. -updated_at.
deletedbooleanFilters annotations based on a deleted property. true will return only deleted annotations, and false will return only non-deleted annotations. Omitting this parameter will return annotations of both types.

Example

Request
GET /api/annotation?deleted=false&scope=organization&order=-date_marker
Response
HTTP 200 OK
Content-Type: application/json
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 107,
"content": "My annotation",
"date_marker": "2021-04-08T14:48:17.987000Z",
"creation_type": "USR",
"dashboard_item": null,
"created_by": {
"id": 1,
"uuid": "0178acc4-8e77-0000-fd90-2ae06832ca61",
"distinct_id": "QD0Q97cv0dPHSlQlVGVHNeAZEr6tETA0Eqtbrl_pYXc",
"first_name": "Demo User",
"email": "demo@posthog.com"
},
"created_at": "2021-04-08T14:48:44.860015Z",
"updated_at": "2021-04-08T14:48:44.860359Z",
"deleted": false,
"scope": "organization"
},
{
"id": 106,
"content": "My other annotation",
"date_marker": "2021-04-08T14:47:55.969000Z",
"creation_type": "USR",
"dashboard_item": null,
"created_by": {
"id": 1,
"uuid": "0178acc4-8e77-0000-fd90-2ae06832ca61",
"distinct_id": "QD0Q97cv0dPHSlQlVGVHNeAZEr6tETA0Eqtbrl_pYXc",
"first_name": "Demo User",
"email": "demo@posthog.com"
},
"created_at": "2021-04-08T14:48:00.592850Z",
"updated_at": "2021-04-08T14:48:00.593266Z",
"deleted": false,
"scope": "organization"
},
]
}


POST
/api/annotation

Create a new annotation.

Request Body

FieldType / Valid ValuesDescriptionRequired
scope- "organization"
- "dashboard_item"
Annotations with scope organization are available on all charts, whereas dashboard_item annotations are associated with one particular chart.
dashboard_itemintA valid ID for a dashboard item to associate the annotation with. Required only if scope is set to dashboard_item.
date_markerstring (ISO Timestamp)Date to associate the annotation with.
contentstringThe content of the annotation.

Example

Request
POST /api/annotation
Request Body
{
content: "new annotation"
dashboard_item: null
date_marker: "2021-04-05T00:00:00.000Z"
scope: "organization"
}
Response
HTTP 201 Created
Content-Type: application/json
{
"id": 112,
"content": "new annotation",
"date_marker": "2021-04-05T00:00:00.000Z",
"creation_type": "USR",
"dashboard_item": null,
"created_by": {
"id": 1,
"uuid": "0178acc4-8e77-0000-fd90-2ae06832ca61",
"distinct_id": "QD0Q97cv0dPHSlQlVGVHNeAZEr6tETA0Eqtbrl_pYXc",
"first_name": "Demo User",
"email": "demo@posthog.com"
},
"created_at": "2021-04-08T15:09:42.940208Z",
"updated_at": "2021-04-08T15:09:42.941011Z",
"deleted": false,
"scope": "organization"
}


PATCH
/api/annotation/<annotation_id:int>

Create a new annotation.

Request Body

FieldType / Valid ValuesDescriptionRequired
scope- "organization"
- "dashboard_item"
Annotations with scope organization are available on all charts, whereas dashboard_item annotations are associated with one particular chart.
dashboard_itemintA valid ID for a dashboard item to associate the annotation with. Required only if scope is set to dashboard_item.
date_markerstring (ISO Timestamp)Date to associate the annotation with.
contentstringThe content of the annotation.
deletedbooleanSpecifies if an annotation is deleted or not.

Example

Request
PATCH /api/annotation/112
Request Body
{
deleted: true
}
Response
HTTP 201 Created
Content-Type: application/json
{
"id": 112,
"content": "new annotation",
"date_marker": "2021-04-05T00:00:00.000Z",
"creation_type": "USR",
"dashboard_item": null,
"created_by": {
"id": 1,
"uuid": "0178acc4-8e77-0000-fd90-2ae06832ca61",
"distinct_id": "QD0Q97cv0dPHSlQlVGVHNeAZEr6tETA0Eqtbrl_pYXc",
"first_name": "Demo User",
"email": "demo@posthog.com"
},
"created_at": "2021-04-08T15:09:42.940208Z",
"updated_at": "2021-04-08T15:09:42.941011Z",
"deleted": true,
"scope": "organization"
}