Skip to content

: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.

39.3 KB
Raw Blame
"""HTTP layer for the Endpoints product.

The viewset is intentionally thin: authentication/permissions, request parsing,
and response serialization. Business logic lives in ``backend/logic``:

- ``logic.crud``: create/update/destroy orchestration + activity logging
- ``logic.execution``: the /run path (materialized / inline / DuckLake)
- ``logic.materialization``: enable/disable/preview materialization
- ``logic.strategies``: HogQL vs insight query behavior
- ``logic.validation``: request payload validation
"""

import re
import builtins
import dataclasses
from typing import Literal, cast
from uuid import UUID

from django.db.models import Count, F, Prefetch
from django.shortcuts import get_object_or_404

from django_filters.rest_framework import DjangoFilterBackend
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema_view
from pydantic import ValidationError as PydanticValidationError
from rest_framework import serializers, status, viewsets
from rest_framework.exceptions import PermissionDenied, ValidationError
from rest_framework.permissions import IsAuthenticated
from rest_framework.request import Request
from rest_framework.response import Response

from posthog.schema import (
    EndpointLastExecutionTimesRequest,
    EndpointRequest,
    EndpointRunRequest,
    QueryStatus,
    QueryStatusResponse,
)

from posthog.api.documentation import extend_schema
from posthog.api.log_entries import LogEntryMixin
from posthog.api.mixins import PydanticModelMixin, ValidatedRequest, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
from posthog.api.tagged_item import TaggedItemViewSetMixin
from posthog.api.utils import action
from posthog.auth import ProjectSecretAPIKeyAuthentication
from posthog.clickhouse.query_tagging import Product
from posthog.exceptions_capture import capture_exception
from posthog.models import TaggedItem, User
from posthog.permissions import (
    APIScopePermission,
    TeamMemberAccessPermission,
    is_authenticated_via_project_secret_api_key,
)
from posthog.schema_migrations.upgrade import upgrade

from products.access_control.backend.facade.user_access_control import access_level_satisfied_for_resource
from products.access_control.backend.presentation.access_control import AccessControlViewSetMixin
from products.data_modeling.backend.facade.api import (
    HasDependentsError,
    allowed_saved_query_ids,
    blocked_lineage_node_id,
    describe_dependents,
)
from products.data_modeling.backend.facade.contracts import Dependent
from products.data_modeling.backend.facade.models import DataModelingJob
from products.endpoints.backend.facade.api import (
    EndpointCrudService,
    EndpointExecutionService,
    EndpointMaterializationService,
    build_materialization_info,
    generate_openapi_spec,
    get_last_execution_times,
    validate_bucket_overrides,
    validate_endpoint_request,
    validate_update_request,
)
from products.endpoints.backend.facade.enums import ENDPOINT_NAME_REGEX, ENDPOINTS_LOG_SOURCE
from products.endpoints.backend.facade.models import Endpoint, EndpointVersion
from products.endpoints.backend.presentation.serializers import (
    EndpointMaterializationSerializer,
    EndpointRequestSerializer,
    EndpointResponseSerializer,
    EndpointRunResponseSerializer,
    EndpointVersionResponseSerializer,
)
from products.endpoints.backend.presentation.throttles import (
    EndpointBurstThrottle,
    EndpointProjectSecretApiKeyTeamBurstThrottle,
    EndpointProjectSecretApiKeyTeamSustainedThrottle,
    EndpointSustainedThrottle,
    charge_inline_rate,
)


class EndpointDependentsValidationError(serializers.ValidationError):
    def __init__(self, detail: str, node_id: str | None = None) -> None:
        super().__init__(detail, code="has_dependents")
        if node_id:
            self.extra = {"node_id": node_id}


class MaterializationPreviewRequestSerializer(serializers.Serializer):
    version = serializers.IntegerField(
        required=False, help_text="Endpoint version to preview. Defaults to the current version."
    )
    bucket_overrides = serializers.DictField(
        child=serializers.CharField(),
        required=False,
        allow_null=True,
        help_text='Per-column bucket function overrides, e.g. {"timestamp": "hour"}',
    )


class MaterializationPreviewRangePairSerializer(serializers.Serializer):
    column = serializers.CharField(help_text="Column the query buckets on.")
    variables = serializers.ListField(
        child=serializers.CharField(),
        help_text="Query variables that filter on this column.",
    )
    bucket_fn = serializers.CharField(help_text="Bucket function applied to the column.")


class MaterializationPreviewAggregateSerializer(serializers.Serializer):
    expression = serializers.CharField(help_text="Aggregate expression in the transformed query.")
    reaggregate_fn = serializers.CharField(
        allow_null=True,
        help_text="Function that combines materialized partials again, or null when there is none.",
    )


class MaterializationPreviewResponseSerializer(serializers.Serializer):
    can_materialize = serializers.BooleanField(help_text="Whether the endpoint query can be materialized.")
    reason = serializers.CharField(
        allow_null=True,
        help_text="Why the query cannot be materialized, or null when it can.",
    )
    transformed_query = serializers.CharField(
        allow_null=True,
        help_text="Query rewritten for materialization, when one could be produced.",
    )
    execution_query = serializers.CharField(
        allow_null=True,
        help_text="Query that would run against the materialized table.",
    )
    display_execution_query = serializers.CharField(
        allow_null=True,
        help_text="Execution query formatted for display.",
    )
    range_pairs = MaterializationPreviewRangePairSerializer(
        many=True,
        help_text="Bucketed columns and the variables that filter on them.",
    )
    aggregates = MaterializationPreviewAggregateSerializer(
        many=True,
        help_text="Aggregate expressions and how to re-aggregate them.",
    )


ENDPOINT_VERSION_PARAMETER = OpenApiParameter(
    name="version",
    type=OpenApiTypes.INT,
    location=OpenApiParameter.QUERY,
    required=False,
    description="Endpoint version to act on. Defaults to the current version.",
)


@extend_schema_view(
    partial_update=extend_schema(
        request=EndpointRequestSerializer,
        responses={200: EndpointResponseSerializer},
        description="Update an existing endpoint.",
    ),
)
class EndpointViewSet(
    TeamAndOrgViewSetMixin,
    AccessControlViewSetMixin,
    PydanticModelMixin,
    TaggedItemViewSetMixin,
    LogEntryMixin,
    viewsets.ModelViewSet,
):
    authentication_classes = [ProjectSecretAPIKeyAuthentication]
    psak_allowed_actions = ["run"]
    scope_object = "endpoint"
    # Read endpoint execution logs from the `log_entries` table keyed by this source.
    log_source = ENDPOINTS_LOG_SOURCE
    # Special case for query - these are all essentially read actions
    scope_object_read_actions = [
        "retrieve",
        "list",
        "run",
        "versions",
        "openapi_spec",
        "materialization_preview",
        "materialization_status",
        "get_endpoints_last_execution_times",
        "logs",
    ]
    scope_object_write_actions: list[str] = [
        "create",
        "destroy",
        "update",
        "partial_update",
    ]
    lookup_field = "name"
    queryset = Endpoint.objects.all()
    filter_backends = [DjangoFilterBackend]
    filterset_fields = ["is_active", "created_by"]

    def safely_get_queryset(self, queryset):
        queryset = queryset.filter(deleted=False)
        if self.action == "list":
            # Offset pages need a fixed order, or rows can repeat or go missing between pages. The
            # partial index on (team, name) for undeleted endpoints serves this order.
            queryset = queryset.order_by("name", "id")
        return queryset

    def get_serializer_class(self):
        return serializers.Serializer  # We use Pydantic models instead; this fallback satisfies drf-spectacular

    def get_throttles(self):
        return [
            EndpointBurstThrottle(),
            EndpointSustainedThrottle(),
            EndpointProjectSecretApiKeyTeamBurstThrottle(),
            EndpointProjectSecretApiKeyTeamSustainedThrottle(),
        ]

    def dangerously_get_permissions(self):
        # `run` is the public-facing execution API. It still requires authentication, the
        # `endpoint:read` API scope, and project membership, but intentionally skips
        # resource-level access control (AccessControlPermission) — a restrictive resource-level
        # default must not break execution for API consumers. Explicit per-endpoint
        # (object-level) denials are still enforced in run() via _enforce_object_level_access.
        if self.action == "run":
            return [permission() for permission in (IsAuthenticated, APIScopePermission, TeamMemberAccessPermission)]
        raise NotImplementedError()

    # ------------------------------------------------------------------
    # Access control helpers
    # ------------------------------------------------------------------

    def _get_endpoint_with_object_access(self, name: str | None) -> Endpoint:
        """Fetch a team-scoped endpoint by name and enforce object-level access controls.

        The custom retrieve/destroy/versions/materialization actions fetch endpoints directly via
        get_object_or_404, which bypasses get_object()'s built-in check_object_permissions. Routing
        through here restores that check so per-endpoint resource access controls (RBAC) are honored,
        not just the resource-level defaults.
        """
        endpoint = get_object_or_404(Endpoint, team=self.team, name=name, deleted=False)
        self.check_object_permissions(self.request, endpoint)
        return endpoint

    def _enforce_object_level_access(self, endpoint: Endpoint) -> None:
        """Block execution only when the user is explicitly denied this specific endpoint via an
        object-level access control. Unlike check_object_permissions, this ignores resource-level
        defaults so a restrictive project default doesn't break the public execution API. Creators
        and org admins always pass (specific_access_level_for_object returns the highest level).
        """
        # PSAK scopes are project-wide and deliberately bypass object-level access controls.
        if is_authenticated_via_project_secret_api_key(self.request):
            return
        specific_level = self.user_access_control.specific_access_level_for_object(endpoint)
        if specific_level is not None and not access_level_satisfied_for_resource("endpoint", specific_level, "viewer"):
            raise PermissionDenied("You do not have access to this endpoint.")

    # ------------------------------------------------------------------
    # Request parsing helpers
    # ------------------------------------------------------------------

    def _parse_version_param(self, request: Request) -> int | None:
        """Parse version number from request body or query params.

        Priority: request.data > query param
        Returns int or None. Raises ValidationError if invalid format.
        """
        body_version = request.data.get("version")
        if body_version is not None:
            try:
                return int(body_version)
            except (ValueError, TypeError):
                raise ValidationError({"version": f"Must be an integer, got: {body_version}"})

        query_version = request.query_params.get("version")
        if query_version is not None:
            try:
                return int(query_version)
            except (ValueError, TypeError):
                raise ValidationError({"version": f"Must be an integer, got: {query_version}"})

        return None

    @staticmethod
    def _parse_int_param(
        body_value: int | None, query_param: str | None, name: str, min_value: int | None = None
    ) -> tuple[int | None, Response | None]:
        """Parse an integer from the request body or query params. Returns (value, error_response)."""
        value = body_value
        if value is None and query_param is not None:
            try:
                value = int(query_param)
                if min_value is not None and value < min_value:
                    raise ValueError()
            except (ValueError, TypeError):
                return None, Response(
                    {"error": f"Invalid {name} parameter: {query_param}"},
                    status=status.HTTP_400_BAD_REQUEST,
                )
        elif value is not None and min_value is not None and value < min_value:
            return None, Response(
                {"error": f"Invalid {name} parameter: {value}"},
                status=status.HTTP_400_BAD_REQUEST,
            )
        return value, None

    def _resolve_version_param(self, request: Request, endpoint: Endpoint) -> EndpointVersion | Response:
        """Resolve the ?version=N param to a version, or a 404 Response if it doesn't exist."""
        version_number = self._parse_version_param(request)
        if version_number is None:
            return endpoint.get_version()
        try:
            return endpoint.get_version(version_number)
        except EndpointVersion.DoesNotExist:
            return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)

    # ------------------------------------------------------------------
    # Serialization
    # ------------------------------------------------------------------

    def _get_tag_names(self, endpoint: Endpoint) -> list[str]:
        """Read tag names from the prefetched cache or from the DB if not prefetched."""
        if hasattr(endpoint, "prefetched_tags"):
            return sorted({ti.tag.name for ti in endpoint.prefetched_tags})
        return sorted(endpoint.tagged_items.values_list("tag__name", flat=True))

    @staticmethod
    def _with_materialization_job_prefetches(queryset):
        latest_jobs = DataModelingJob.objects.filter(engine=DataModelingJob.Engine.CLICKHOUSE).order_by("-last_run_at")
        latest_completed_jobs = latest_jobs.filter(status=DataModelingJob.Status.COMPLETED)
        return queryset.select_related("saved_query", "team").prefetch_related(
            EndpointVersion.frequency_nodes_prefetch(),
            Prefetch("saved_query__datamodelingjob_set", queryset=latest_jobs[:1], to_attr="prefetched_latest_jobs"),
            Prefetch(
                "saved_query__datamodelingjob_set",
                queryset=latest_completed_jobs[:1],
                to_attr="prefetched_latest_completed_jobs",
            ),
        )

    @classmethod
    def _with_serialization_prefetches(cls, queryset):
        """Tags are prefetched by TaggedItemViewSetMixin.filter_queryset; repeating them here
        raises a lookup conflict.

        Only the current version is fetched, and the history is counted in the database, so an
        endpoint with a long version history costs the same as a fresh one.
        """
        current_versions = cls._with_materialization_job_prefetches(
            EndpointVersion.objects.filter(version=F("endpoint__current_version"))
        )
        return (
            queryset.select_related("created_by")
            .prefetch_related(
                Prefetch(
                    "versions",
                    queryset=current_versions,
                    to_attr="prefetched_current_versions",
                ),
            )
            .annotate(versions_count=Count("versions", distinct=True))
        )

    @staticmethod
    def _current_version(endpoint: Endpoint) -> EndpointVersion:
        """Read the current version from the prefetch, falling back to a query.

        The prefetch is empty if `current_version` ever drifts from the versions actually stored,
        so the fallback also covers that.
        """
        prefetched = getattr(endpoint, "prefetched_current_versions", None)
        if prefetched:
            return prefetched[0]
        return endpoint.get_version()

    @staticmethod
    def _versions_count(endpoint: Endpoint) -> int:
        annotated = getattr(endpoint, "versions_count", None)
        if annotated is not None:
            return annotated
        return endpoint.versions.count()

    def _serialize(
        self,
        obj: Endpoint | EndpointVersion,
        request: Request | None = None,
    ) -> dict:
        """Serialize an Endpoint or EndpointVersion.

        Both return the same base fields. EndpointVersion adds version-specific fields.
        """
        if isinstance(obj, EndpointVersion):
            endpoint = obj.endpoint
            version = obj
        else:
            endpoint = obj
            version = self._current_version(endpoint)

        versions_count = (
            obj.endpoint_versions_count
            if isinstance(obj, EndpointVersion) and hasattr(obj, "endpoint_versions_count")
            else self._versions_count(endpoint)
        )

        url = None
        ui_url = None
        if request:
            url = request.build_absolute_uri(endpoint.endpoint_path)
            ui_path = f"/project/{endpoint.team_id}/endpoints/{endpoint.name}"
            ui_url = request.build_absolute_uri(ui_path)

        result = {
            "id": str(endpoint.id),
            "name": endpoint.name,
            "description": version.description,
            "query": version.query,
            "is_active": version.is_active if isinstance(obj, EndpointVersion) else endpoint.is_active,
            "data_freshness_seconds": version.data_freshness_seconds,
            "endpoint_path": endpoint.endpoint_path,
            "url": url,
            "ui_url": ui_url,
            "created_at": endpoint.created_at,
            "updated_at": endpoint.updated_at,
            "created_by": UserBasicSerializer(endpoint.created_by).data if hasattr(endpoint, "created_by") else None,
            "is_materialized": version.is_materialized,
            "current_version": endpoint.current_version,
            "current_version_id": str(version.id),
            "versions_count": versions_count,
            "derived_from_insight": endpoint.derived_from_insight,
            "last_executed_at": endpoint.last_executed_at.isoformat() if endpoint.last_executed_at else None,
            "materialization": build_materialization_info(version),
            "bucket_overrides": version.bucket_overrides,
            "columns": version.get_columns() if version else [],
            "tags": self._get_tag_names(endpoint),
            "optional_breakdown_properties": list(version.optional_breakdown_properties or []),
        }

        if isinstance(obj, EndpointVersion):
            result["version"] = version.version
            result["version_id"] = str(version.id)
            result["endpoint_is_active"] = endpoint.is_active
            # Version detail returns the version's own execution time (may be null until it's been run).
            result["last_executed_at"] = version.last_executed_at.isoformat() if version.last_executed_at else None
            result["version_created_at"] = version.created_at.isoformat()
            result["version_updated_at"] = version.updated_at.isoformat() if version.updated_at else None
            result["version_created_by"] = UserBasicSerializer(version.created_by).data if version.created_by else None

        return result

    # ------------------------------------------------------------------
    # CRUD actions
    # ------------------------------------------------------------------

    @extend_schema(
        responses={200: EndpointResponseSerializer(many=True)},
        description="List all endpoints for the team.",
    )
    def list(self, request: Request, *args, **kwargs) -> Response:
        """List all endpoints for the team."""
        queryset = self._with_serialization_prefetches(self.filter_queryset(self.get_queryset()))
        page = self.paginate_queryset(queryset)
        if page is not None:
            results = [self._serialize(endpoint, request) for endpoint in page]
            return self.get_paginated_response(results)
        results = [self._serialize(endpoint, request) for endpoint in queryset]
        return Response({"results": results})

    @extend_schema(
        parameters=[ENDPOINT_VERSION_PARAMETER],
        responses={200: EndpointVersionResponseSerializer},
        description="Retrieve an endpoint, or a specific version via ?version=N.",
    )
    def retrieve(self, request: Request, name=None, *args, **kwargs) -> Response:
        """Retrieve an endpoint, or a specific endpoint version."""
        endpoint = self._get_endpoint_with_object_access(name)

        version_number = self._parse_version_param(request)
        try:
            if version_number is not None:
                try:
                    version = endpoint.get_version(version_number)
                    return Response(self._serialize(version), status=status.HTTP_200_OK)
                except EndpointVersion.DoesNotExist:
                    return Response(
                        {"error": f"Version {version_number} not found"},
                        status=status.HTTP_404_NOT_FOUND,
                    )

            return Response(self._serialize(endpoint, request), status=status.HTTP_200_OK)
        except Exception as e:
            capture_exception(e, {"endpoint_name": endpoint.name, "team_id": self.team_id})
            raise ValidationError("Failed to retrieve endpoint.")

    @extend_schema(
        request=EndpointRequestSerializer,
        responses={201: EndpointResponseSerializer},
        description="Create a new endpoint.",
    )
    def create(self, request: Request, *args, **kwargs) -> Response:
        """Create a new endpoint."""
        upgraded_query = upgrade(request.data)
        data = self.get_model(upgraded_query, EndpointRequest)
        validate_endpoint_request(data, self.team, cast(User, request.user), strict=True)

        endpoint = EndpointCrudService(self.team, request).create(data)

        return Response(
            self._serialize(endpoint, request),
            status=status.HTTP_201_CREATED,
        )

    @extend_schema(
        request=EndpointRequestSerializer,
        responses={200: EndpointResponseSerializer},
        description="Update an existing endpoint. Parameters are optional. Pass version in body or ?version=N query param to target a specific version.",
    )
    def update(self, request: Request, name: str | None = None, *args, **kwargs) -> Response:
        """Update an existing endpoint.

        Supports version from body or query params (body takes precedence).
        If version is specified, updates target that specific version.
        Otherwise, the current version is used.
        """
        # Enforce object-level RBAC: a user with global editor scope can still be restricted
        # from a specific endpoint via per-object access controls.
        endpoint = self._get_endpoint_with_object_access(name)

        upgraded_query = upgrade(request.data)
        data = self.get_model(upgraded_query, EndpointRequest)

        # Soft-delete via PATCH {deleted: true} — reuses destroy() logic, returns 200 with body for MCP
        if data.deleted is True:
            self.destroy(request, name=name)
            return Response({"success": True}, status=status.HTTP_200_OK)

        version_number = self._parse_version_param(request)
        validate_update_request(
            data, self.team, cast(User, request.user), endpoint=endpoint, version_number=version_number
        )

        try:
            outcome = EndpointCrudService(self.team, request).update(endpoint, data, request.data, version_number)
        except HasDependentsError as error:
            raise self._dependents_error(endpoint.name, error, action="turn off materialization for")

        # When targeting a specific version, return version data; otherwise return endpoint data
        if outcome.version_targeted and outcome.target_version is not None:
            result = self._serialize(outcome.target_version)
        else:
            result = self._serialize(outcome.endpoint, request)

        if outcome.materialization_error:
            result["materialization_error"] = outcome.materialization_error

        return Response(result)

    def destroy(self, request: Request, name=None, *args, **kwargs) -> Response:
        """Delete an endpoint and clean up materialized query."""
        endpoint = self._get_endpoint_with_object_access(name)
        try:
            EndpointCrudService(self.team, request).destroy(endpoint)
        except HasDependentsError as error:
            raise self._dependents_error(error.view_name, error)
        return Response(status=status.HTTP_204_NO_CONTENT)

    def _dependents_error(
        self,
        subject_name: str,
        error: HasDependentsError,
        *,
        action: Literal["delete", "turn off materialization for"] = "delete",
    ) -> EndpointDependentsValidationError:
        visible = self._visible_dependents(error.dependents)
        can_read_lineage = self.user_access_control.check_access_level_for_resource(
            "warehouse_view", required_level="viewer"
        )
        return EndpointDependentsValidationError(
            describe_dependents(
                subject_name,
                visible,
                any_hidden=len(visible) < len(error.dependents),
                action=action,
            ),
            node_id=blocked_lineage_node_id(visible, error.fallback_node_id) if can_read_lineage else None,
        )

    def _visible_dependents(self, dependents: tuple[Dependent, ...]) -> builtins.list[Dependent]:
        endpoint_dependents = [dependent for dependent in dependents if dependent.kind == "endpoint"]
        endpoint_saved_query_ids = [
            dependent.saved_query_id for dependent in endpoint_dependents if dependent.saved_query_id is not None
        ]
        endpoint_names = [dependent.name for dependent in endpoint_dependents if dependent.saved_query_id is None]
        endpoint_versions = EndpointVersion.objects.filter(
            endpoint__team=self.team,
            saved_query_id__in=endpoint_saved_query_ids,
        ).select_related("endpoint")
        endpoints = {
            endpoint.id: endpoint
            for endpoint in [
                *(version.endpoint for version in endpoint_versions),
                *Endpoint.objects.filter(team=self.team, name__in=endpoint_names, deleted=False),
            ]
        }
        self.user_access_control.preload_object_access_controls(list(endpoints.values()))
        readable_endpoint_ids = {
            str(endpoint.id)
            for endpoint in endpoints.values()
            if self.user_access_control.check_access_level_for_object(endpoint, "viewer")
        }
        endpoint_ids_by_saved_query = {
            str(version.saved_query_id): str(version.endpoint_id) for version in endpoint_versions
        }
        endpoint_ids_by_name = {endpoint.name: str(endpoint.id) for endpoint in endpoints.values()}

        saved_query_ids = [
            UUID(dependent.saved_query_id)
            for dependent in dependents
            if dependent.kind not in {"endpoint", "metric"} and dependent.saved_query_id is not None
        ]
        readable_saved_query_ids = {
            str(saved_query_id)
            for saved_query_id in allowed_saved_query_ids(
                self.team_id,
                self.user_access_control,
                ids=saved_query_ids,
            )
        }
        metrics_readable = self.user_access_control.check_access_level_for_resource(
            "data_catalog", required_level="viewer"
        )

        return [
            dependent
            for dependent in dependents
            if (
                (
                    dependent.kind == "endpoint"
                    and (
                        endpoint_ids_by_saved_query.get(dependent.saved_query_id or "")
                        or endpoint_ids_by_name.get(dependent.name)
                    )
                    in readable_endpoint_ids
                )
                or (dependent.kind == "metric" and metrics_readable)
                or (
                    dependent.kind not in {"endpoint", "metric"}
                    and dependent.saved_query_id in readable_saved_query_ids
                )
            )
        ]

    # ------------------------------------------------------------------
    # Execution
    # ------------------------------------------------------------------

    @staticmethod
    def _parse_run_request(request: Request) -> EndpointRunRequest:
        """Parse the run body into field-level errors instead of pydantic's raw error dump."""
        try:
            return EndpointRunRequest.model_validate(request.data)
        except PydanticValidationError as exc:
            field_errors = {
                ".".join(str(part) for part in error["loc"]) or "body": error["msg"] for error in exc.errors()
            }
            raise ValidationError(field_errors) from exc

    @staticmethod
    def _rejection_reason(response: Response) -> str:
        data = response.data
        if isinstance(data, dict):
            return str(data.get("error", data))
        return str(data)

    @extend_schema(
        request=EndpointRunRequest,
        responses={200: EndpointRunResponseSerializer},
        description="Execute endpoint with optional materialization. Supports version parameter, runs latest version if not set.",
    )
    @action(methods=["GET", "POST"], detail=True)
    def run(self, request: Request, name=None, *args, **kwargs) -> Response:
        """Execute endpoint with optional parameters."""
        endpoint = get_object_or_404(Endpoint, team=self.team, name=name, is_active=True, deleted=False)
        self._enforce_object_level_access(endpoint)
        service = EndpointExecutionService(self.team, request)
        try:
            data = self._parse_run_request(request)
        except ValidationError as exc:
            service.log_rejected_run(endpoint, service.format_validation_detail(exc.detail))
            raise

        version_number, err = self._parse_int_param(data.version, request.query_params.get("version"), "version")
        if err:
            service.log_rejected_run(endpoint, self._rejection_reason(err))
            return err
        limit, err = self._parse_int_param(data.limit, request.query_params.get("limit"), "limit", min_value=1)
        if err:
            service.log_rejected_run(endpoint, self._rejection_reason(err))
            return err
        offset, err = self._parse_int_param(data.offset, request.query_params.get("offset"), "offset", min_value=0)
        if err:
            service.log_rejected_run(endpoint, self._rejection_reason(err))
            return err

        if offset is not None and limit is None:
            response = Response(
                {"error": "offset requires limit to be set"},
                status=status.HTTP_400_BAD_REQUEST,
            )
            service.log_rejected_run(endpoint, self._rejection_reason(response))
            return response

        version_obj = None
        try:
            version_obj = endpoint.get_version(version_number)
        except EndpointVersion.DoesNotExist:
            if version_number is not None:
                response = Response(
                    {
                        "error": f"Version {version_number} not found for endpoint '{name}'",
                        "current_version": endpoint.current_version,
                    },
                    status=status.HTTP_404_NOT_FOUND,
                )
                service.log_rejected_run(endpoint, self._rejection_reason(response))
                return response

        return service.execute(
            endpoint,
            data,
            version_obj,
            limit=limit,
            offset=offset,
            before_inline_fallback=lambda: charge_inline_rate(request, self),
        )

    @extend_schema(
        description=(
            "Get the most recent execution time per endpoint (endpoint-level). "
            "Timestamps are recorded by the run path for personal-API-key calls. "
            "For per-version usage, query the query_log table directly."
        ),
        request=EndpointLastExecutionTimesRequest,
        responses={200: QueryStatusResponse},
    )
    @action(methods=["POST"], detail=False, url_path="last_execution_times")
    def get_endpoints_last_execution_times(self, request: Request, *args, **kwargs) -> Response:
        try:
            data = EndpointLastExecutionTimesRequest.model_validate(request.data)
            names = data.names
            if not names:
                return Response(
                    QueryStatusResponse(
                        query_status=QueryStatus(id="", team_id=self.team.pk, complete=True)
                    ).model_dump(),
                    status=200,
                )

            for name in names:
                if not isinstance(name, str) or not re.fullmatch(ENDPOINT_NAME_REGEX, name):
                    raise ValidationError({"names": f"Invalid endpoint name: {name}"})

            results = [[name, ts.isoformat()] for name, ts in get_last_execution_times(self.team.pk, names)]

            query_status = QueryStatus(id="", team_id=self.team.pk, complete=True, results=results)

            return Response(QueryStatusResponse(query_status=query_status).model_dump(), status=200)
        except Exception as e:
            capture_exception(e, {"product": Product.ENDPOINTS, "team_id": self.team_id})
            raise

    # ------------------------------------------------------------------
    # Versions + materialization
    # ------------------------------------------------------------------

    @extend_schema(
        responses={200: EndpointVersionResponseSerializer(many=True)},
        description="List all versions for an endpoint.",
    )
    @action(methods=["GET"], detail=True)
    def versions(self, request: Request, name=None, *args, **kwargs) -> Response:
        """List all versions for an endpoint.

        Returns versions in descending order (latest first).
        """
        endpoint = self._get_endpoint_with_object_access(name)
        versions_qs = (
            self._with_materialization_job_prefetches(endpoint.versions.all())
            .select_related("endpoint", "endpoint__created_by", "created_by")
            .prefetch_related(
                Prefetch(
                    "endpoint__tagged_items",
                    queryset=TaggedItem.objects.select_related("tag"),
                    to_attr="prefetched_tags",
                )
            )
            .annotate(endpoint_versions_count=Count("endpoint__versions", distinct=True))
            .order_by("-version")
        )
        page = self.paginate_queryset(versions_qs)
        if page is not None:
            results = [self._serialize(v) for v in page]
            return self.get_paginated_response(results)
        results = [self._serialize(v) for v in versions_qs]
        return Response({"results": results})

    @extend_schema(
        parameters=[ENDPOINT_VERSION_PARAMETER],
        responses={200: EndpointMaterializationSerializer},
        description="Get materialization status for an endpoint. Supports ?version=N query param.",
    )
    @action(methods=["GET"], detail=True, url_path="materialization_status")
    def materialization_status(self, request: Request, name=None, *args, **kwargs) -> Response:
        """Get materialization status for an endpoint without fetching full endpoint data.

        Supports ?version=N query param to get status for a specific version.
        """
        endpoint = self._get_endpoint_with_object_access(name)

        version = self._resolve_version_param(request, endpoint)
        if isinstance(version, Response):
            return version

        return Response(build_materialization_info(version, endpoint_name=endpoint.name))

    @validated_request(
        MaterializationPreviewRequestSerializer,
        responses={200: OpenApiResponse(response=MaterializationPreviewResponseSerializer)},
        description="Preview the materialization transform for an endpoint. Shows what the query will look like after materialization, including range pair detection and bucket functions.",
    )
    @action(methods=["POST"], detail=True, url_path="materialization_preview")
    def materialization_preview(self, request: ValidatedRequest, name=None, *args, **kwargs) -> Response:
        """Preview the materialization transform without enabling it.

        Returns the transformed query, range pair info, and aggregate re-aggregation info.
        """
        endpoint = self._get_endpoint_with_object_access(name)

        version_number = request.validated_data.get("version")
        if version_number is not None:
            try:
                version = endpoint.get_version(version_number)
            except EndpointVersion.DoesNotExist:
                return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)
        else:
            version = endpoint.get_version()

        bucket_overrides = request.validated_data.get("bucket_overrides")
        if bucket_overrides:
            validate_bucket_overrides(bucket_overrides)

        service = EndpointMaterializationService(self.team, request)
        return Response(dataclasses.asdict(service.preview(endpoint, version, bucket_overrides)))

    @extend_schema(
        # url_path="openapi.json" would otherwise produce `..._openapi.json_retrieve` —
        # the `.` is rejected by lint_spec_consistency_hook + the MCP YAML scaffolder.
        operation_id="endpoints_openapi_spec_retrieve",
        description="Get OpenAPI 3.0 specification for this endpoint. Use this to generate typed SDK clients.",
        parameters=[ENDPOINT_VERSION_PARAMETER],
    )
    @action(methods=["GET"], detail=True, url_path="openapi.json")
    def openapi_spec(self, request: Request, name=None, *args, **kwargs) -> Response:
        """Generate OpenAPI 3.0 specification for this endpoint.

        Returns a spec that can be used with tools like openapi-generator,
        `@hey-api/openapi-ts`, or any other OpenAPI-compatible SDK generator.

        Supports ?version=N query param to generate spec for a specific version.
        """
        endpoint = self._get_endpoint_with_object_access(name)

        version = None
        version_number = self._parse_version_param(request)
        if version_number is not None:
            try:
                version = endpoint.get_version(version_number)
            except EndpointVersion.DoesNotExist:
                return Response({"error": f"Version {version_number} not found"}, status=status.HTTP_404_NOT_FOUND)

        spec = generate_openapi_spec(endpoint, self.team.id, request, version)
        return Response(spec, content_type="application/json")

    # ------------------------------------------------------------------
    # Tags
    # ------------------------------------------------------------------

    @extend_schema(exclude=True)
    @action(methods=["POST"], detail=False)
    def bulk_update_tags(self, request: Request, *args, **kwargs) -> Response:
        # The inherited TaggedItemViewSetMixin.bulk_update_tags assumes integer PKs (its
        # BulkUpdateTagsRequestSerializer validates ids as IntegerField). Endpoint uses
        # UUID PKs, so the action is unusable. Return 405 until the mixin gains UUID support.
        return Response(
            {"detail": "Bulk tag updates are not supported for endpoints."},
            status=status.HTTP_405_METHOD_NOT_ALLOWED,
        )