:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from datetime import datetime
from typing import Any, Literal
from django.db.models import Q, QuerySet
from rest_framework import filters, serializers, viewsets
from posthog.api.forbid_destroy_model import ForbidDestroyModel
from posthog.api.pagination import BoundedLimitOffsetPagination
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.scoped_related_fields import TeamScopedPrimaryKeyRelatedField
from posthog.api.shared import UserBasicSerializer
from posthog.models.user import User
from posthog.models.utils import strict_fetch
from products.annotations.backend.models.annotation import Annotation
from products.dashboards.backend.models.dashboard import Dashboard
from products.product_analytics.backend.facade.models import Insight
class AnnotationSerializer(serializers.ModelSerializer):
created_by = UserBasicSerializer(read_only=True)
# Soft-deleted parents resolve here because the frontend echoes both FKs back on every write. A
# project-scoped annotation whose dashboard was deleted would otherwise be impossible to edit or
# delete. Only the pointer the annotation already stores may be echoed. Every other deleted
# parent answers as if it does not exist. validate() then rejects a write whose own scope points
# at a soft-deleted parent.
dashboard_id = serializers.IntegerField(
required=False,
allow_null=True,
help_text="Optional dashboard ID to attach this annotation to. Must belong to the current project.",
)
dashboard_item = TeamScopedPrimaryKeyRelatedField(
queryset=Insight.objects_including_soft_deleted.all(),
required=False,
allow_null=True,
help_text="Optional insight ID to attach this annotation to. Must belong to the current project.",
)
class Meta:
model = Annotation
fields = [
"id",
"content",
"date_marker",
"creation_type",
"dashboard_item",
"dashboard_id",
"dashboard_name",
"insight_short_id",
"insight_name",
"insight_derived_name",
"created_by",
"created_at",
"updated_at",
"deleted",
"scope",
"emoji",
"hidden_in_user_interface",
]
read_only_fields = [
"id",
"insight_short_id",
"insight_name",
"insight_derived_name",
"dashboard_name",
"created_by",
"created_at",
"updated_at",
]
extra_kwargs = {
"content": {
"help_text": "Annotation text shown on charts to describe the change, release, or incident.",
},
"date_marker": {
"help_text": "When this annotation happened (ISO 8601 timestamp). Used to position it on charts.",
},
"creation_type": {
"help_text": "Who created this annotation. Use `USR` for user-created notes and `GIT` for bot/deployment notes.",
},
"deleted": {
"help_text": "Soft-delete flag. Set to true to hide the annotation, or false to restore it.",
},
"scope": {
"help_text": (
"Annotation visibility scope: `project`, `organization`, `dashboard`, or `dashboard_item`. "
"`recording` is deprecated and rejected."
),
},
"emoji": {
"help_text": "Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.",
"required": False,
"allow_null": True,
"allow_blank": True,
},
"hidden_in_user_interface": {
"help_text": (
"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."
),
"required": False,
"allow_null": True,
},
}
def validate_emoji(self, value: str | None) -> str | None:
# Normalise blank strings to None so the DB has a single canonical "no emoji" state.
return value or None
def validate_dashboard_item(self, value: Insight | None) -> Insight | None:
# A deleted insight answers exactly as an unknown one does unless the annotation already
# points at it, so a guessed ID cannot report back its name.
if value is not None and value.deleted and value.pk != getattr(self.instance, "dashboard_item_id", None):
self.fields["dashboard_item"].fail("does_not_exist", pk_value=value.pk)
return value
def update(self, instance: Annotation, validated_data: dict[str, Any]) -> Annotation:
instance.team_id = self.context["team_id"]
return super().update(instance, validated_data)
def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
team = self.context["get_team"]()
scope = attrs.get("scope", None)
if scope == Annotation.Scope.RECORDING.value:
raise serializers.ValidationError("Recording scope is deprecated")
# Resolve the parents the annotation will have after this write. A key absent from `attrs`
# keeps the stored value, while a key present but null clears it, so membership is what
# distinguishes the two on a PATCH.
dashboard = None
if "dashboard_id" in attrs:
if attrs["dashboard_id"] is not None:
dashboard = Dashboard.objects_including_soft_deleted.filter(
id=attrs["dashboard_id"], team_id=team.id
).first()
# A deleted dashboard answers exactly as an unknown one does unless the annotation
# already points at it, so a guessed ID cannot report back its name.
if dashboard is None or (
dashboard.deleted and dashboard.id != getattr(self.instance, "dashboard_id", None)
):
raise serializers.ValidationError({"dashboard_id": "Dashboard not found."})
if dashboard.id != getattr(self.instance, "dashboard_id", None):
self._require_viewer_access(dashboard, "dashboard_id", "dashboard")
elif self.instance is not None:
dashboard = self.instance.dashboard
if "dashboard_item" in attrs:
insight = attrs["dashboard_item"]
if insight is not None and insight.pk != getattr(self.instance, "dashboard_item_id", None):
self._require_viewer_access(insight, "dashboard_item", "insight")
else:
insight = getattr(self.instance, "dashboard_item", None)
# A create checks only an explicit scope, because rows created without one take the model
# default and have no insight. An update checks the scope the row will have, so clearing the
# parent is caught too. A row already stored without its parent, such as a default row or one
# whose dashboard was hard-deleted, stays editable, because the UI echoes its scope back.
instance = self.instance
checked_scope = scope if instance is None else scope or instance.scope
if (
checked_scope == Annotation.Scope.INSIGHT.value
and insight is None
and not (instance is not None and instance.scope == checked_scope and instance.dashboard_item_id is None)
):
raise serializers.ValidationError(
{"dashboard_item": "Set `dashboard_item` to the insight ID when the scope is `dashboard_item`."}
)
if (
checked_scope == Annotation.Scope.DASHBOARD.value
and dashboard is None
and not (instance is not None and instance.scope == checked_scope and instance.dashboard_id is None)
):
raise serializers.ValidationError(
{"dashboard_id": "Set `dashboard_id` to the dashboard ID when the scope is `dashboard`."}
)
# AnnotationsViewSet.safely_get_queryset hides an annotation whose own scope points at a
# soft-deleted parent, so accepting one here would strand a row that nothing can list, edit
# or delete. Project- and organization-scoped rows keep their pointers, which are only used
# to show where the annotation was created.
effective_scope = scope or getattr(self.instance, "scope", Annotation.Scope.INSIGHT.value)
if effective_scope == Annotation.Scope.INSIGHT.value and insight is not None and insight.deleted:
raise serializers.ValidationError(
{"dashboard_item": "This insight is deleted. Restore it, or pick a different scope."}
)
if effective_scope == Annotation.Scope.DASHBOARD.value and dashboard is not None and dashboard.deleted:
raise serializers.ValidationError(
{"dashboard_id": "This dashboard is deleted. Restore it, or pick a different scope."}
)
return attrs
def _require_viewer_access(
self, parent: Dashboard | Insight, field: str, resource: Literal["dashboard", "insight"]
) -> None:
user_access_control = self.context["view"].user_access_control
if isinstance(self.context["request"].user, User) and user_access_control.denied_object_ids(
resource, [(str(parent.pk), parent.team_id, parent.created_by_id)], "viewer"
):
raise serializers.ValidationError({field: f"You need viewer access to this {resource} to annotate it."})
def create(self, validated_data: dict[str, Any], *args: Any, **kwargs: Any) -> Annotation:
request = self.context["request"]
team = self.context["get_team"]()
annotation = Annotation.objects.create(
organization_id=team.organization_id,
team_id=team.id,
created_by=request.user,
**validated_data,
)
return annotation
class AnnotationsLimitOffsetPagination(BoundedLimitOffsetPagination):
default_limit = 1000
class AnnotationsViewSet(TeamAndOrgViewSetMixin, ForbidDestroyModel, viewsets.ModelViewSet):
"""
Create, Read, Update and Delete annotations. [See docs](https://posthog.com/docs/data/annotations) for more information on annotations.
"""
scope_object = "annotation"
queryset = (
Annotation.objects.select_related("dashboard_item").select_related("dashboard").select_related("created_by")
)
serializer_class = AnnotationSerializer
filter_backends = [filters.SearchFilter]
pagination_class = AnnotationsLimitOffsetPagination
search_fields = ["content"]
def safely_get_queryset(self, queryset) -> QuerySet:
if self.action == "list":
# `date_marker` alone is not a total order, so limit-offset pages can repeat or drop rows.
queryset = strict_fetch(queryset.order_by("-date_marker", "-id"))
if self.action != "partial_update":
# We never want deleted items to be included in the queryset… except when we want to restore an annotation
# That's because annotations are restored with a PATCH request setting `deleted` to `False`
queryset = queryset.filter(deleted=False)
# Annotations scoped to a soft-deleted insight or dashboard are hidden
# across all actions, including `partial_update`, so they cannot be
# individually edited or restored while their parent is soft-deleted.
# They reappear automatically when the parent is restored. Mirrors how
# alerts behave (see posthog/temporal/alerts/activities.py).
# Gated on scope: every annotation records the insight and dashboard it was
# created from, so a project- or organization-scoped one would otherwise
# disappear project-wide once that parent is deleted.
queryset = queryset.exclude(scope=Annotation.Scope.INSIGHT, dashboard_item__deleted=True).exclude(
scope=Annotation.Scope.DASHBOARD, dashboard__deleted=True
)
scope = self.request.query_params.get("scope")
if scope:
# let's allow the more recently used "insight" scope to be used as "dashboard_item"
scope = "dashboard_item" if scope == "insight" else scope
if scope not in [scope.value for scope in Annotation.Scope]:
raise serializers.ValidationError(f"Invalid scope: {scope}")
queryset = queryset.filter(scope=scope)
# Add date range filtering
date_from = self.request.query_params.get("date_from")
date_to = self.request.query_params.get("date_to")
date_from_parsed = None
date_to_parsed = None
if date_from:
try:
date_from_parsed = datetime.fromisoformat(date_from.replace("Z", "+00:00"))
queryset = queryset.filter(date_marker__gte=date_from_parsed)
except ValueError:
raise serializers.ValidationError("Invalid date range: date_from must be a valid ISO 8601 date")
if date_to:
try:
date_to_parsed = datetime.fromisoformat(date_to.replace("Z", "+00:00"))
queryset = queryset.filter(date_marker__lte=date_to_parsed)
except ValueError:
raise serializers.ValidationError("Invalid date range: date_to must be a valid ISO 8601 date")
if date_from_parsed and date_to_parsed and date_from_parsed > date_to_parsed:
raise serializers.ValidationError("Invalid date range: date_from must be before date_to")
# Add is_emoji filtering
is_emoji = self.request.query_params.get("is_emoji")
if is_emoji is not None:
# Convert string to boolean (true, 1, yes -> True; false, 0, no -> False)
is_emoji_bool = is_emoji.lower() in ("true", "1", "yes")
queryset = queryset.filter(is_emoji=is_emoji_bool)
hidden_in_user_interface = self.request.query_params.get("hidden_in_user_interface")
if hidden_in_user_interface is not None:
if hidden_in_user_interface.lower() in ("true", "1", "yes"):
queryset = queryset.filter(hidden_in_user_interface=True)
else:
queryset = queryset.filter(Q(hidden_in_user_interface=False) | Q(hidden_in_user_interface__isnull=True))
return queryset
def _filter_queryset_by_parents_lookups(self, queryset):
team = self.team
return queryset.filter(
Q(scope=Annotation.Scope.ORGANIZATION, organization_id=team.organization_id) | Q(team=team)
)