PostHog · Schema

EndpointRequest

Schema for creating/updating endpoints. OpenAPI docs only — validation uses Pydantic.

A/B TestingAnalyticsFeature FlagsOpen SourceProduct AnalyticsSession Recording

Properties

Name	Type	Description
name	string	Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars.
query	object	HogQL or insight query this endpoint executes. Changing this auto-creates a new version.
description	string	Human-readable description of what this endpoint returns.
data_freshness_seconds	integer	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 materializatio
is_active	boolean	Whether this endpoint is available for execution via the API.
is_materialized	boolean	Whether query results are materialized to S3.
derived_from_insight	string	Short ID of the insight this endpoint was derived from.
version	integer	Target a specific version for updates (defaults to current version).
bucket_overrides	object	Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.
deleted	boolean	Set to true to soft-delete this endpoint.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/EndpointRequest",
  "title": "EndpointRequest",
  "type": "object",
  "description": "Schema for creating/updating endpoints. OpenAPI docs only \u2014 validation uses Pydantic.",
  "properties": {
    "name": {
      "type": "string",
      "nullable": true,
      "description": "Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars."
    },
    "query": {
      "nullable": true,
      "description": "HogQL or insight query this endpoint executes. Changing this auto-creates a new version."
    },
    "description": {
      "type": "string",
      "nullable": true,
      "description": "Human-readable description of what this endpoint returns."
    },
    "data_freshness_seconds": {
      "type": "integer",
      "nullable": true,
      "description": "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": {
      "type": "boolean",
      "nullable": true,
      "description": "Whether this endpoint is available for execution via the API."
    },
    "is_materialized": {
      "type": "boolean",
      "nullable": true,
      "description": "Whether query results are materialized to S3."
    },
    "derived_from_insight": {
      "type": "string",
      "nullable": true,
      "description": "Short ID of the insight this endpoint was derived from."
    },
    "version": {
      "type": "integer",
      "nullable": true,
      "description": "Target a specific version for updates (defaults to current version)."
    },
    "bucket_overrides": {
      "type": "object",
      "additionalProperties": true,
      "nullable": true,
      "description": "Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys."
    },
    "deleted": {
      "type": "boolean",
      "nullable": true,
      "description": "Set to true to soft-delete this endpoint."
    }
  }
}