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.

10.7 KB
Raw Blame
"""OpenAPI schema serializers for the Endpoints product.

These serializers document request/response shapes for drf-spectacular.
They do NOT replace the existing Pydantic validation or manual _serialize() logic —
they exist so the OpenAPI spec (and downstream MCP tools / generated TypeScript) gets
accurate type information and descriptions.
"""

from rest_framework import serializers

from posthog.api.shared import UserBasicSerializer


class EndpointRequestSerializer(serializers.Serializer):
    """Schema for creating/updating endpoints. OpenAPI docs only — validation uses Pydantic."""

    name = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars.",
    )
    query = serializers.JSONField(
        required=False,
        allow_null=True,
        help_text="HogQL or insight query this endpoint executes. Changing this auto-creates a new version.",
    )
    description = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Human-readable description of what this endpoint returns.",
    )
    data_freshness_seconds = serializers.IntegerField(
        required=False,
        allow_null=True,
        help_text=(
            "How fresh the data should be, in seconds. Must be one of: "
            "900 (15 min), 1800 (30 min), 3600 (1 h), 21600 (6 h), 43200 (12 h), "
            "86400 (24 h, default), 604800 (7 d). Controls cache TTL and materialization sync frequency."
        ),
    )
    is_active = serializers.BooleanField(
        required=False,
        allow_null=True,
        help_text="Whether this endpoint is available for execution via the API.",
    )
    is_materialized = serializers.BooleanField(
        required=False,
        allow_null=True,
        help_text="Whether query results are materialized to S3.",
    )
    derived_from_insight = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Short ID of the insight this endpoint was derived from.",
    )
    version = serializers.IntegerField(
        required=False,
        allow_null=True,
        help_text="Target a specific version for updates (defaults to current version).",
    )
    bucket_overrides = serializers.DictField(
        required=False,
        allow_null=True,
        help_text="Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.",
    )
    deleted = serializers.BooleanField(
        required=False,
        allow_null=True,
        help_text="Set to true to soft-delete this endpoint.",
    )
    tags = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        allow_null=True,
        help_text="List of tag names to associate with this endpoint. Replaces any existing tags.",
    )
    optional_breakdown_properties = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        allow_null=True,
        help_text=(
            "Breakdown property names that may be omitted on /run. Omitted ones return data aggregated "
            "across all values of that breakdown. Defaults to [] — every breakdown variable is required."
        ),
    )


class EndpointMaterializationSerializer(serializers.Serializer):
    """Materialization status for an endpoint version."""

    name = serializers.CharField(
        help_text="URL-safe endpoint name.",
    )
    enabled = serializers.BooleanField(
        help_text="Whether materialization is enabled for this endpoint version.",
    )
    ready = serializers.BooleanField(
        help_text="Whether a successful materialization is available to serve.",
    )
    status = serializers.CharField(
        required=False,
        help_text="Current materialization status (e.g. 'Completed', 'Running').",
    )
    can_materialize = serializers.BooleanField(
        help_text="Whether this endpoint query can be materialized.",
    )
    reason = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Reason why materialization is not possible (only when can_materialize is false).",
    )
    last_materialized_at = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="ISO 8601 timestamp of the last successful materialization.",
    )
    error = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Last materialization error message, if any.",
    )
    saved_query_id = serializers.UUIDField(
        required=False,
        allow_null=True,
        help_text="UUID of the underlying saved query backing this materialization. Only populated when the version is materialized.",
    )


class EndpointColumnSerializer(serializers.Serializer):
    """A column in the endpoint's query result."""

    name = serializers.CharField(help_text="Column name from the query SELECT clause.")
    type = serializers.CharField(
        help_text="Serialized column type: integer, float, string, datetime, date, boolean, array, json, or unknown.",
    )


class EndpointResponseSerializer(serializers.Serializer):
    """Full endpoint representation returned by list/retrieve/create/update."""

    id = serializers.UUIDField(help_text="Unique endpoint identifier (UUID).")
    name = serializers.CharField(help_text="URL-safe endpoint name, unique per team.")
    description = serializers.CharField(
        allow_null=True,
        allow_blank=True,
        help_text="Human-readable description of the endpoint.",
    )
    query = serializers.JSONField(
        help_text="The HogQL or insight query definition (JSON object with 'kind' key).",
    )
    is_active = serializers.BooleanField(
        help_text="Whether the endpoint can be executed via the API.",
    )
    data_freshness_seconds = serializers.IntegerField(
        help_text=(
            "Effective data freshness, in seconds. Materialized endpoints use the node's refresh target, "
            "which can differ from the standard freshness choices. Other endpoints use the cache duration."
        ),
    )
    endpoint_path = serializers.CharField(
        help_text="Relative API path to execute this endpoint (e.g. /api/projects/{team_id}/endpoints/{name}/run).",
    )
    url = serializers.CharField(
        allow_null=True,
        help_text="Absolute URL to execute this endpoint.",
    )
    ui_url = serializers.CharField(
        allow_null=True,
        help_text="Absolute URL to view this endpoint in the PostHog UI.",
    )
    created_at = serializers.DateTimeField(help_text="When the endpoint was created (ISO 8601).")
    updated_at = serializers.DateTimeField(help_text="When the endpoint was last updated (ISO 8601).")
    created_by = UserBasicSerializer(
        read_only=True,
        help_text="User who created the endpoint.",
    )
    is_materialized = serializers.BooleanField(
        help_text="Whether the current version's results are pre-computed to S3.",
    )
    current_version = serializers.IntegerField(help_text="Latest version number.")

    current_version_id = serializers.UUIDField(
        required=False,
        allow_null=True,
        help_text="UUID of the current EndpointVersion row.",
    )

    versions_count = serializers.IntegerField(help_text="Total number of versions for this endpoint.")
    derived_from_insight = serializers.CharField(
        allow_null=True,
        help_text="Short ID of the source insight, if derived from one.",
    )
    last_executed_at = serializers.DateTimeField(
        allow_null=True,
        help_text="When this endpoint was last executed via the API (ISO 8601), or null if never executed.",
    )
    materialization = EndpointMaterializationSerializer(
        help_text="Materialization status and configuration for the current version.",
    )
    bucket_overrides = serializers.DictField(
        allow_null=True,
        help_text="Per-column bucket overrides for range variable materialization.",
    )
    columns = EndpointColumnSerializer(
        many=True,
        help_text="Column names and types from the query's SELECT clause.",
    )
    tags = serializers.ListField(
        child=serializers.CharField(),
        help_text="Tag names associated with this endpoint.",
    )
    optional_breakdown_properties = serializers.ListField(
        child=serializers.CharField(),
        help_text=(
            "Breakdown property names that may be omitted on /run. Omitted ones return data aggregated "
            "across all values of that breakdown."
        ),
    )


class EndpointRunResponseSerializer(serializers.Serializer):
    """Response from executing an endpoint query."""

    name = serializers.CharField(help_text="URL-safe endpoint name that was executed.")
    execution_id = serializers.UUIDField(
        required=False,
        help_text="Unique identifier for this execution. Use it to find the matching entry in the endpoint's logs.",
    )
    results = serializers.ListField(
        required=False,
        help_text="Query result rows. Each row is a list of values matching the columns order.",
    )
    columns = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        help_text="Column names from the query SELECT clause.",
    )
    hasMore = serializers.BooleanField(
        required=False,
        help_text="Whether more results are available beyond the limit.",
    )
    endpoint_version = serializers.IntegerField(
        required=False,
        help_text="Version number of the endpoint that was executed.",
    )


class EndpointVersionResponseSerializer(EndpointResponseSerializer):
    """Extended endpoint representation when viewing a specific version."""

    last_executed_at = serializers.DateTimeField(
        allow_null=True,
        help_text=(
            "When this specific version was last executed via the API (ISO 8601), or null if it hasn't "
            "been executed. Per-version tracking is recent, so versions that predate it read null until "
            "their next run."
        ),
    )
    version = serializers.IntegerField(help_text="Version number.")
    version_id = serializers.UUIDField(help_text="Version unique identifier (UUID).")
    endpoint_is_active = serializers.BooleanField(
        help_text="Whether the parent endpoint is active (distinct from version.is_active).",
    )
    version_created_at = serializers.CharField(
        help_text="ISO 8601 timestamp when this version was created.",
    )
    version_updated_at = serializers.CharField(
        allow_null=True,
        help_text="ISO 8601 timestamp when this version was last updated.",
    )
    version_created_by = UserBasicSerializer(
        read_only=True,
        allow_null=True,
        help_text="User who created this version.",
    )