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"
}