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.

25.3 KB
Raw Blame
/**
 * Auto-generated from the Django backend OpenAPI schema.
 * MCP service uses these Zod schemas for generated tool handlers.
 * To regenerate: hogli build:openapi
 *
 * PostHog API - MCP 13 enabled ops
 * OpenAPI spec version: 1.0.0
 */
import * as zod from 'zod'

/**
 * Aggregated heatmap interactions for a page. For type 'click'/'rageclick'/'mousemove' each result is a point with relative x, absolute client-y, and a count. For type 'scrolldepth' the response is scroll-depth buckets instead (cumulative reach down the page).
 */
export const HeatmapsListParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const heatmapsListQueryAggregationDefault = `total_count`
export const heatmapsListQueryDateFromDefault = `-7d`

export const heatmapsListQueryHideZeroCoordinatesDefault = true
export const heatmapsListQueryLimitDefault = 500
export const heatmapsListQueryLimitMin = 0
export const heatmapsListQueryLimitMax = 1000000

export const heatmapsListQueryOffsetDefault = 0
export const heatmapsListQueryOffsetMin = 0
export const heatmapsListQueryOffsetMax = 1000000

export const heatmapsListQueryTypeDefault = `click`

export const HeatmapsListQueryParams = () => zod.object({
    aggregation: zod
        .enum(['unique_visitors', 'total_count'])
        .default(heatmapsListQueryAggregationDefault)
        .describe(
            "How to aggregate counts: 'total_count' (every interaction, default) or 'unique_visitors' (distinct people).\n\n\* `unique_visitors` - unique_visitors\n\* `total_count` - total_count"
        ),
    cohort_ids: zod
        .string()
        .nullish()
        .describe(
            "JSON array of cohort IDs (e.g. '[123, 456]') to restrict results to people in those cohorts. Feature-flagged; ignored when the cohort filter is not enabled for the caller."
        ),
    date_from: zod
        .string()
        .min(1)
        .default(heatmapsListQueryDateFromDefault)
        .describe(
            "Start of the window. Relative (e.g. '-7d', '-30d', '-1mStart') or an absolute 'YYYY-MM-DD' date. Defaults to '-7d'. Heatmap data is retained for 90 days."
        ),
    date_to: zod
        .string()
        .min(1)
        .optional()
        .describe("End of the window, inclusive. Relative or absolute 'YYYY-MM-DD'. Defaults to today."),
    events: zod
        .string()
        .nullish()
        .describe(
            "JSON array of event filters (e.g. '[{\"id\": \"purchase\", \"properties\": []}]') to restrict results to sessions in which those events occurred. Each entry needs a string 'id' (the event name) and may carry a 'properties' array of property filters applied to that event, each of type 'event' or 'element'. Several entries are combined with AND: the session must contain a matching event for every entry. At most 10 entries, each with at most 20 property filters. Requires project-wide heatmap access, since the filter reads the project's events rather than one saved heatmap. Feature-flagged; ignored when the event filter is not enabled for the caller."
        ),
    filter_test_accounts: zod
        .boolean()
        .nullish()
        .describe("When true, exclude sessions from internal\/test accounts using the project's test-account filters."),
    hide_zero_coordinates: zod
        .boolean()
        .default(heatmapsListQueryHideZeroCoordinatesDefault)
        .describe('When true (default), drop interactions recorded at the (0, 0) origin, which are usually noise.'),
    limit: zod
        .number()
        .min(heatmapsListQueryLimitMin)
        .max(heatmapsListQueryLimitMax)
        .default(heatmapsListQueryLimitDefault)
        .describe(
            "Maximum number of coordinate points to return, ordered hottest-first by count. Defaults to 500. Pass 0 to fetch the full set (every coordinate) needed to render a complete heatmap overlay. Ignored for the 'scrolldepth' type, which always returns every bucket."
        ),
    offset: zod
        .number()
        .min(heatmapsListQueryOffsetMin)
        .max(heatmapsListQueryOffsetMax)
        .default(heatmapsListQueryOffsetDefault)
        .describe(
            "Number of hottest-first points to skip, for paging through cooler coordinates. Ignored for the 'scrolldepth' type."
        ),
    timestamp_from: zod.iso
        .datetime({ offset: true })
        .optional()
        .describe('Inclusive UTC instant. Supply with timestamp_to to override date bounds.'),
    timestamp_to: zod.iso
        .datetime({ offset: true })
        .optional()
        .describe('Exclusive UTC instant. Supply with timestamp_from to override date bounds.'),
    type: zod
        .string()
        .min(1)
        .default(heatmapsListQueryTypeDefault)
        .describe(
            "The interaction type to return. One of: 'click' (default), 'rageclick', 'mousemove', or 'scrolldepth'. Scrolldepth returns scroll buckets instead of x\/y coordinates."
        ),
    url_exact: zod
        .string()
        .min(1)
        .optional()
        .describe('Match a single page by exact URL (trailing slash is ignored). Mutually exclusive with url_pattern.'),
    url_pattern: zod
        .string()
        .min(1)
        .optional()
        .describe(
            'Match pages by regex against the full current_url (anchored automatically). Use this to aggregate across query strings or path segments. Mutually exclusive with url_exact.'
        ),
    viewport_width_max: zod
        .number()
        .optional()
        .describe('Only include interactions captured at a viewport at most this wide, in CSS pixels.'),
    viewport_width_min: zod
        .number()
        .optional()
        .describe(
            'Only include interactions captured at a viewport at least this wide, in CSS pixels. Use with viewport_width_max to isolate a device class (e.g. 360-768 for mobile).'
        ),
})

/**
 * Drill into the individual session interactions behind one or more heatmap coordinates. Pass the 'points' you want to inspect (from the heatmaps list response) to get the underlying per-session events, so you can jump to the session recordings that produced a hotspot.
 */
export const HeatmapsEventsRetrieveParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const heatmapsEventsRetrieveQueryAggregationDefault = `total_count`
export const heatmapsEventsRetrieveQueryDateFromDefault = `-7d`

export const heatmapsEventsRetrieveQueryHideZeroCoordinatesDefault = true
export const heatmapsEventsRetrieveQueryLimitDefault = 50
export const heatmapsEventsRetrieveQueryLimitMax = 100

export const heatmapsEventsRetrieveQueryOffsetDefault = 0
export const heatmapsEventsRetrieveQueryOffsetMin = 0

export const heatmapsEventsRetrieveQueryTypeDefault = `click`

export const HeatmapsEventsRetrieveQueryParams = () => zod.object({
    aggregation: zod
        .enum(['unique_visitors', 'total_count'])
        .default(heatmapsEventsRetrieveQueryAggregationDefault)
        .describe(
            "How to aggregate counts: 'total_count' (every interaction, default) or 'unique_visitors' (distinct people).\n\n\* `unique_visitors` - unique_visitors\n\* `total_count` - total_count"
        ),
    cohort_ids: zod
        .string()
        .nullish()
        .describe(
            "JSON array of cohort IDs (e.g. '[123, 456]') to restrict results to people in those cohorts. Feature-flagged; ignored when the cohort filter is not enabled for the caller."
        ),
    date_from: zod
        .string()
        .min(1)
        .default(heatmapsEventsRetrieveQueryDateFromDefault)
        .describe(
            "Start of the window. Relative (e.g. '-7d', '-30d', '-1mStart') or an absolute 'YYYY-MM-DD' date. Defaults to '-7d'. Heatmap data is retained for 90 days."
        ),
    date_to: zod
        .string()
        .min(1)
        .optional()
        .describe("End of the window, inclusive. Relative or absolute 'YYYY-MM-DD'. Defaults to today."),
    events: zod
        .string()
        .nullish()
        .describe(
            "JSON array of event filters (e.g. '[{\"id\": \"purchase\", \"properties\": []}]') to restrict results to sessions in which those events occurred. Each entry needs a string 'id' (the event name) and may carry a 'properties' array of property filters applied to that event, each of type 'event' or 'element'. Several entries are combined with AND: the session must contain a matching event for every entry. At most 10 entries, each with at most 20 property filters. Requires project-wide heatmap access, since the filter reads the project's events rather than one saved heatmap. Feature-flagged; ignored when the event filter is not enabled for the caller."
        ),
    filter_test_accounts: zod
        .boolean()
        .nullish()
        .describe("When true, exclude sessions from internal\/test accounts using the project's test-account filters."),
    hide_zero_coordinates: zod
        .boolean()
        .default(heatmapsEventsRetrieveQueryHideZeroCoordinatesDefault)
        .describe('When true (default), drop interactions recorded at the (0, 0) origin, which are usually noise.'),
    limit: zod
        .number()
        .min(1)
        .max(heatmapsEventsRetrieveQueryLimitMax)
        .default(heatmapsEventsRetrieveQueryLimitDefault)
        .describe('Maximum interactions to return (1-100).'),
    offset: zod
        .number()
        .min(heatmapsEventsRetrieveQueryOffsetMin)
        .default(heatmapsEventsRetrieveQueryOffsetDefault)
        .describe('Number of interactions to skip, for pagination.'),
    points: zod
        .string()
        .min(1)
        .describe(
            "JSON array of the heatmap coordinates to drill into, e.g. '[{\"x\": 0.5, \"y\": 100}]'. Each point needs 'x' (relative x, 0..1) and 'y' (absolute client-y pixels) matching values returned by the heatmaps list endpoint; an optional 'target_fixed' boolean matches fixed-position elements. Returns the individual session interactions behind those spots."
        ),
    timestamp_from: zod.iso
        .datetime({ offset: true })
        .optional()
        .describe('Inclusive UTC instant. Supply with timestamp_to to override date bounds.'),
    timestamp_to: zod.iso
        .datetime({ offset: true })
        .optional()
        .describe('Exclusive UTC instant. Supply with timestamp_from to override date bounds.'),
    type: zod
        .string()
        .min(1)
        .default(heatmapsEventsRetrieveQueryTypeDefault)
        .describe(
            "The interaction type to return. One of: 'click' (default), 'rageclick', 'mousemove', or 'scrolldepth'. Scrolldepth returns scroll buckets instead of x\/y coordinates."
        ),
    url_exact: zod
        .string()
        .min(1)
        .optional()
        .describe('Match a single page by exact URL (trailing slash is ignored). Mutually exclusive with url_pattern.'),
    url_pattern: zod
        .string()
        .min(1)
        .optional()
        .describe(
            'Match pages by regex against the full current_url (anchored automatically). Use this to aggregate across query strings or path segments. Mutually exclusive with url_exact.'
        ),
    viewport_width_max: zod
        .number()
        .optional()
        .describe('Only include interactions captured at a viewport at most this wide, in CSS pixels.'),
    viewport_width_min: zod
        .number()
        .optional()
        .describe(
            'Only include interactions captured at a viewport at least this wide, in CSS pixels. Use with viewport_width_max to isolate a device class (e.g. 360-768 for mobile).'
        ),
})

/**
 * List saved heatmaps for the project. A saved heatmap pins a page URL and a set of viewport widths, and (for type 'screenshot') renders the page so heatmap data can be overlaid on it.
 */
export const SavedListParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const savedListQueryLimitDefault = 100
export const savedListQueryOffsetDefault = 0

export const SavedListQueryParams = () => zod.object({
    created_by: zod.number().optional().describe("Filter by the creating user's ID."),
    limit: zod.number().default(savedListQueryLimitDefault).describe('Maximum saved heatmaps to return.'),
    offset: zod.number().default(savedListQueryOffsetDefault).describe('Number to skip, for pagination.'),
    order: zod.string().min(1).optional().describe("Field to order by, e.g. '-updated_at' (default) or 'created_at'."),
    search: zod.string().min(1).optional().describe('Case-insensitive substring match on URL or name.'),
    status: zod
        .string()
        .min(1)
        .optional()
        .describe("Filter by generation status: 'processing', 'completed', or 'failed'."),
    type: zod.string().min(1).optional().describe("Filter by render mode: 'screenshot', 'iframe', or 'recording'."),
})

/**
 * Create a saved heatmap for a page URL. For type 'screenshot' (the default) this enqueues a headless render of the page at each target width; poll the saved heatmap or its content endpoint until status is 'completed'. Provide 'widths' to control which viewport widths are rendered.
 */
export const SavedCreateParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const savedCreateBodyNameMax = 400

export const savedCreateBodyUrlMax = 2000

export const savedCreateBodyDataUrlOneMax = 2000

export const savedCreateBodyDataUrlTwoMax = 0

export const savedCreateBodyWidthsItemMin = 100
export const savedCreateBodyWidthsItemMax = 3000

export const savedCreateBodyWidthsMax = 16

export const savedCreateBodyTypeDefault = `screenshot`

export const SavedCreateBody = () => zod.object({
    name: zod.string().max(savedCreateBodyNameMax).nullish().describe('Human-readable label for the saved heatmap.'),
    url: zod
        .url()
        .max(savedCreateBodyUrlMax)
        .describe('Exact page URL to render and overlay heatmap data on. Wildcards are not allowed.'),
    data_url: zod
        .union([zod.url().max(savedCreateBodyDataUrlOneMax).nullable(), zod.string().max(savedCreateBodyDataUrlTwoMax)])
        .optional()
        .describe("URL whose heatmap data is overlaid on the screenshot. Defaults to 'url' when omitted."),
    widths: zod
        .array(zod.number().min(savedCreateBodyWidthsItemMin).max(savedCreateBodyWidthsItemMax))
        .max(savedCreateBodyWidthsMax)
        .optional()
        .describe(
            'Viewport widths (px, 100-3000) to render the heatmap screenshot at — one render per width. Defaults to [320, 375, 425, 768, 1024, 1440, 1920] when omitted. At most 16 widths.'
        ),
    type: zod
        .enum(['screenshot', 'iframe', 'recording'])
        .describe('\* `screenshot` - Screenshot\n\* `iframe` - Iframe\n\* `recording` - Recording')
        .default(savedCreateBodyTypeDefault)
        .describe(
            "Render mode: 'screenshot' (renders the page headlessly, default), 'iframe', or 'recording'. Only 'screenshot' generates image bytes.\n\n\* `screenshot` - Screenshot\n\* `iframe` - Iframe\n\* `recording` - Recording"
        ),
    block_consent_modals: zod
        .boolean()
        .optional()
        .describe(
            "When true, ask the headless browser to dismiss cookie\/consent banners before capturing the screenshot. Off by default: the blocker can stall the render on some sites and time out. Only applies to 'screenshot' heatmaps."
        ),
})

/**
 * Get a single saved heatmap by its short_id, including per-width render status.
 */
export const SavedRetrieveParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
    short_id: zod.string(),
})

/**
 * Update a saved heatmap (e.g. rename, change widths, or soft-delete via 'deleted'). Changing the URL of a 'screenshot' heatmap triggers a re-render.
 */
export const SavedPartialUpdateParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
    short_id: zod.string(),
})

export const savedPartialUpdateBodyNameMax = 400

export const savedPartialUpdateBodyUrlMax = 2000

export const savedPartialUpdateBodyDataUrlOneMax = 2000

export const savedPartialUpdateBodyDataUrlTwoMax = 0

export const savedPartialUpdateBodyWidthsItemMin = 100
export const savedPartialUpdateBodyWidthsItemMax = 3000

export const savedPartialUpdateBodyWidthsMax = 16

export const SavedPartialUpdateBody = () => zod.object({
    name: zod
        .string()
        .max(savedPartialUpdateBodyNameMax)
        .nullish()
        .describe('Human-readable label for the saved heatmap.'),
    url: zod
        .url()
        .max(savedPartialUpdateBodyUrlMax)
        .optional()
        .describe('Exact page URL to render and overlay heatmap data on. Wildcards are not allowed.'),
    data_url: zod
        .union([
            zod.url().max(savedPartialUpdateBodyDataUrlOneMax).nullable(),
            zod.string().max(savedPartialUpdateBodyDataUrlTwoMax),
        ])
        .optional()
        .describe("URL whose heatmap data is overlaid on the screenshot. Defaults to 'url' when omitted."),
    widths: zod
        .array(zod.number().min(savedPartialUpdateBodyWidthsItemMin).max(savedPartialUpdateBodyWidthsItemMax))
        .max(savedPartialUpdateBodyWidthsMax)
        .optional()
        .describe(
            'Viewport widths (px, 100-3000) to render the heatmap screenshot at — one render per width. Defaults to [320, 375, 425, 768, 1024, 1440, 1920] when omitted. At most 16 widths.'
        ),
    type: zod
        .enum(['screenshot', 'iframe', 'recording'])
        .describe('\* `screenshot` - Screenshot\n\* `iframe` - Iframe\n\* `recording` - Recording')
        .optional()
        .describe(
            "Render mode: 'screenshot' (renders the page headlessly, default), 'iframe', or 'recording'. Only 'screenshot' generates image bytes.\n\n\* `screenshot` - Screenshot\n\* `iframe` - Iframe\n\* `recording` - Recording"
        ),
    deleted: zod.boolean().optional().describe('Set true to soft-delete the saved heatmap.'),
    block_consent_modals: zod
        .boolean()
        .optional()
        .describe(
            "When true, ask the headless browser to dismiss cookie\/consent banners before capturing the screenshot. Off by default: the blocker can stall the render on some sites and time out. Only applies to 'screenshot' heatmaps."
        ),
})

/**
 * Re-run screenshot generation for a saved heatmap of type 'screenshot'. Clears existing renders and re-renders at every target width; status returns to 'processing'.
 */
export const SavedRegenerateCreateParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
    short_id: zod.string(),
})

/**
 * Summarizes a project's web analytics over a lookback window (default 7 days): unique visitors, pageviews, sessions, bounce rate, and average session duration with period-over-period comparisons, plus the top 5 pages, top 5 traffic sources, and goal conversions.
 * @summary Summarize web analytics
 */
export const WebAnalyticsWeeklyDigestParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const webAnalyticsWeeklyDigestQueryCompareDefault = true
export const webAnalyticsWeeklyDigestQueryDaysDefault = 7

export const WebAnalyticsWeeklyDigestQueryParams = () => zod.object({
    compare: zod
        .boolean()
        .default(webAnalyticsWeeklyDigestQueryCompareDefault)
        .describe(
            'When true (default), include period-over-period change for each metric comparing against the prior equal-length period. Set to false to skip the comparison query (faster).'
        ),
    days: zod
        .number()
        .default(webAnalyticsWeeklyDigestQueryDaysDefault)
        .describe('Lookback window in days (1–90). Defaults to 7.'),
})

/**
 * The project's own bot rules, in the order they are checked at query time.
 * @summary List custom bot rules
 */
export const WebAnalyticsBotRulesListParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

/**
 * Add one bot rule to the project. A rule combines one or more single-property conditions with AND or OR. A pattern is rejected if it cannot run, because a broken rule would break every query that classifies traffic for the project.
 * @summary Create a custom bot rule
 */
export const WebAnalyticsBotRulesCreateParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

export const webAnalyticsBotRulesCreateBodyCombinerDefault = `AND`
export const webAnalyticsBotRulesCreateBodyItemsItemIdMax = 100

export const WebAnalyticsBotRulesCreateBody = () => zod.object({
    name: zod
        .string()
        .describe(
            'Label reported by the `Bot name` property when the rule matches. Also the operator for a rule on a bot PostHog does not know.'
        ),
    category: zod
        .string()
        .optional()
        .describe(
            "Reported by the `Traffic category` property. Defaults to 'custom'. A built-in category such as ai_crawler or search_crawler relabels the traffic type too."
        ),
    combiner: zod
        .string()
        .default(webAnalyticsBotRulesCreateBodyCombinerDefault)
        .describe(
            "How the conditions combine: 'AND' flags an event only when every condition matches, 'OR' when any one of them does."
        ),
    items: zod
        .array(
            zod.object({
                id: zod
                    .string()
                    .max(webAnalyticsBotRulesCreateBodyItemsItemIdMax)
                    .optional()
                    .describe('Stable id for the condition. Generated when omitted.'),
                key: zod
                    .string()
                    .describe(
                        'Event property the condition reads. One of: $raw_user_agent, $ip, $lib, $host, $pathname, $current_url, $browser, $os, $browser_language, $screen_width, $screen_height, $geoip_country_code, $referrer, $referring_domain.'
                    ),
                matcher: zod
                    .string()
                    .describe(
                        "How `pattern` is compared: 'contains' (case-insensitive substring), 'regex' (RE2), 'exact' (case-sensitive equality), or 'cidr' (an IP network range, only valid with the `$ip` property)."
                    ),
                pattern: zod
                    .string()
                    .describe(
                        "Value matched against the property named by `key`. For 'cidr' this is a network range like 192.0.2.0\/24."
                    ),
            })
        )
        .describe('The conditions of this rule. Each one reads a single event property.'),
})

/**
 * Remove one bot rule by its id. The built-in bot list is unaffected.
 * @summary Delete a custom bot rule
 */
export const WebAnalyticsBotRulesDestroyParams = () => zod.object({
    id: zod.string(),
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

/**
 * Merges the suggestion's rules into the team's path_cleaning_filters (never overwrites existing rules) and resolves the underlying health issue. Requires project admin, matching the team API's gate on path_cleaning_filters.
 * @summary Apply a path-cleaning suggestion
 */
export const WebAnalyticsPathCleaningSuggestionsApplyParams = () => zod.object({
    id: zod.string(),
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})

/**
 * Samples the team's recent paths, asks the LLM for cleaning rules, validates them against the real paths, and stores the result as a `path_cleaning_suggestions` health issue (replacing any previous active one). Runs even if the team already has rules. Returns the suggestion (or a skip status when there aren't enough paths to suggest from).
 * @summary Generate path-cleaning suggestions on demand
 */
export const WebAnalyticsPathCleaningSuggestionsGenerateParams = () => zod.object({
    project_id: zod
        .string()
        .describe(
            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
        ),
})