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.

16.7 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 7 enabled ops
 * OpenAPI spec version: 1.0.0
 */
import * as zod from 'zod'

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsListParams = () => 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 personsListQueryLimitMax = 1000

export const personsListQueryPropertiesItemTypeDefault = `AND`
export const personsListQueryPropertiesItemValuesItemOperatorDefault = `exact`
export const personsListQueryPropertiesItemValuesItemTypeDefault = `event`

export const PersonsListQueryParams = () => zod.object({
    client_query_id: zod
        .string()
        .optional()
        .describe(
            'Names the ClickHouse query this request runs. Send the same id to `DELETE \/api\/projects\/:project_id\/query\/:client_query_id\/` to stop a search that is still running. Up to 128 characters.'
        ),
    distinct_id: zod.string().optional().describe('Filter list by distinct id.'),
    email: zod.string().optional().describe('Filter persons by email (exact match)'),
    format: zod.enum(['csv', 'json']).optional(),
    include_matched_fields: zod
        .boolean()
        .optional()
        .describe(
            'Tag each search result with `matched_fields`, the searched fields the term was found in. A complete email address that exactly matches a distinct ID then returns that person first, followed by every person whose email or name property contains the address.'
        ),
    limit: zod.number().max(personsListQueryLimitMax).optional().describe('Number of results to return per page.'),
    offset: zod.number().optional().describe('The initial index from which to return the results.'),
    properties: zod
        .array(
            zod.object({
                type: zod
                    .enum(['AND', 'OR'])
                    .default(personsListQueryPropertiesItemTypeDefault)
                    .describe(
                        '\n You can use a simplified version:\n```json\n{\n    \"properties\": [\n        {\n            \"key\": \"email\",\n            \"value\": \"[email protected]\",\n            \"operator\": \"exact\",\n            \"type\": \"event\"\n        }\n    ]\n}\n```\n\nOr you can create more complicated queries with AND and OR:\n```json\n{\n    \"properties\": {\n        \"type\": \"AND\",\n        \"values\": [\n            {\n                \"type\": \"OR\",\n                \"values\": [\n                    {\"key\": \"email\", ...},\n                    {\"key\": \"email\", ...}\n                ]\n            },\n            {\n                \"type\": \"AND\",\n                \"values\": [\n                    {\"key\": \"email\", ...},\n                    {\"key\": \"email\", ...}\n                ]\n            }\n        ]\n    ]\n}\n```\n\n\n\* `AND` - AND\n\* `OR` - OR'
                    ),
                values: zod.array(
                    zod.object({
                        key: zod
                            .string()
                            .describe("Key of the property you're filtering on. For example `email` or `$current_url`"),
                        value: zod
                            .union([
                                zod.string(),
                                zod.number(),
                                zod.boolean(),
                                zod.array(zod.union([zod.string(), zod.number()])),
                            ])
                            .describe(
                                'Value of your filter. For example `[email protected]` or `https:\/\/example.com\/test\/`. Can be an array for an OR query, like `[\"[email protected]\",\"[email protected]\"]`'
                            ),
                        operator: zod
                            .union([
                                zod
                                    .enum([
                                        'exact',
                                        'is_not',
                                        'icontains',
                                        'not_icontains',
                                        'starts_with',
                                        'not_starts_with',
                                        'ends_with',
                                        'not_ends_with',
                                        'regex',
                                        'not_regex',
                                        'gt',
                                        'lt',
                                        'gte',
                                        'lte',
                                        'is_set',
                                        'is_not_set',
                                        'is_date_exact',
                                        'is_date_after',
                                        'is_date_before',
                                        'in',
                                        'not_in',
                                    ])
                                    .describe(
                                        '\* `exact` - exact\n\* `is_not` - is_not\n\* `icontains` - icontains\n\* `not_icontains` - not_icontains\n\* `starts_with` - starts_with\n\* `not_starts_with` - not_starts_with\n\* `ends_with` - ends_with\n\* `not_ends_with` - not_ends_with\n\* `regex` - regex\n\* `not_regex` - not_regex\n\* `gt` - gt\n\* `lt` - lt\n\* `gte` - gte\n\* `lte` - lte\n\* `is_set` - is_set\n\* `is_not_set` - is_not_set\n\* `is_date_exact` - is_date_exact\n\* `is_date_after` - is_date_after\n\* `is_date_before` - is_date_before\n\* `in` - in\n\* `not_in` - not_in'
                                    ),
                                zod.enum(['']),
                                zod.null(),
                            ])
                            .default(personsListQueryPropertiesItemValuesItemOperatorDefault),
                        type: zod
                            .union([
                                zod
                                    .enum([
                                        'event',
                                        'event_metadata',
                                        'feature',
                                        'person',
                                        'person_metadata',
                                        'cohort',
                                        'element',
                                        'static-cohort',
                                        'dynamic-cohort',
                                        'precalculated-cohort',
                                        'group',
                                        'recording',
                                        'log_entry',
                                        'behavioral',
                                        'session',
                                        'hogql',
                                        'data_warehouse',
                                        'data_warehouse_person_property',
                                        'error_tracking_issue',
                                        'log',
                                        'log_attribute',
                                        'log_resource_attribute',
                                        'metric_attribute',
                                        'span',
                                        'span_attribute',
                                        'span_resource_attribute',
                                        'revenue_analytics',
                                        'account_custom_property',
                                        'flag',
                                        'workflow_variable',
                                    ])
                                    .describe(
                                        '\* `event` - event\n\* `event_metadata` - event_metadata\n\* `feature` - feature\n\* `person` - person\n\* `person_metadata` - person_metadata\n\* `cohort` - cohort\n\* `element` - element\n\* `static-cohort` - static-cohort\n\* `dynamic-cohort` - dynamic-cohort\n\* `precalculated-cohort` - precalculated-cohort\n\* `group` - group\n\* `recording` - recording\n\* `log_entry` - log_entry\n\* `behavioral` - behavioral\n\* `session` - session\n\* `hogql` - hogql\n\* `data_warehouse` - data_warehouse\n\* `data_warehouse_person_property` - data_warehouse_person_property\n\* `error_tracking_issue` - error_tracking_issue\n\* `log` - log\n\* `log_attribute` - log_attribute\n\* `log_resource_attribute` - log_resource_attribute\n\* `metric_attribute` - metric_attribute\n\* `span` - span\n\* `span_attribute` - span_attribute\n\* `span_resource_attribute` - span_resource_attribute\n\* `revenue_analytics` - revenue_analytics\n\* `account_custom_property` - account_custom_property\n\* `flag` - flag\n\* `workflow_variable` - workflow_variable'
                                    ),
                                zod.enum(['']),
                            ])
                            .default(personsListQueryPropertiesItemValuesItemTypeDefault),
                    })
                ),
            })
        )
        .optional()
        .describe('Filter Persons by person properties.'),
    search: zod
        .string()
        .optional()
        .describe(
            'Search persons by email, name, person ID, or distinct ID. Partial values match. When the term is a complete email address or UUID that exactly matches a distinct ID or person ID, only that person is returned.'
        ),
})

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsRetrieveParams = () => zod.object({
    id: zod.string().describe('A unique value identifying this person. Accepts both numeric ID and UUID.'),
    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 PersonsRetrieveQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
})

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsDeletePropertyCreateParams = () => zod.object({
    id: zod.string().describe('A unique value identifying this person. Accepts both numeric ID and UUID.'),
    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 PersonsDeletePropertyCreateQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
})

export const personsDeletePropertyCreateBodyUnsetTwoMax = 1000

export const PersonsDeletePropertyCreateBody = () => zod.object({
    $unset: zod
        .union([
            zod.string().min(1),
            zod.array(zod.string().min(1)).min(1).max(personsDeletePropertyCreateBodyUnsetTwoMax),
        ])
        .describe('A property key, or a list of property keys, to remove from this person.'),
})

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsUpdatePropertyCreateParams = () => zod.object({
    id: zod.string().describe('A unique value identifying this person. Accepts both numeric ID and UUID.'),
    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 PersonsUpdatePropertyCreateQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
})

export const PersonsUpdatePropertyCreateBody = () => zod.object({
    key: zod.string().optional().describe("The property key to set. Pair it with 'value' to set one property."),
    value: zod.unknown().optional().describe('The property value. Can be a string, number, boolean, or object.'),
    properties: zod
        .record(zod.string(), zod.unknown())
        .optional()
        .describe(
            "Property keys and values to set together, instead of 'key' and 'value'. One request sets up to 1000 properties and emits a single $set event."
        ),
})

/**
 * This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs. You can pass in a maximum of 1000 IDs per call. Only events captured before the request will be deleted.
 *
 * Person records are removed in the background shortly after the request returns, so a successful response reports them in `persons_queued_for_deletion` and `persons_deleted` is 0.
 */
export const PersonsBulkDeleteCreateParams = () => 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 PersonsBulkDeleteCreateQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
})

export const personsBulkDeleteCreateBodyDeleteEventsDefault = false
export const personsBulkDeleteCreateBodyDeleteRecordingsDefault = false
export const personsBulkDeleteCreateBodyKeepPersonDefault = false

export const PersonsBulkDeleteCreateBody = () => zod.object({
    ids: zod.array(zod.string()).optional().describe('A list of PostHog person UUIDs to delete (max 1000).'),
    distinct_ids: zod
        .array(zod.string())
        .optional()
        .describe('A list of distinct IDs whose associated persons will be deleted (max 1000).'),
    delete_events: zod
        .boolean()
        .default(personsBulkDeleteCreateBodyDeleteEventsDefault)
        .describe('If true, queue deletion of all events associated with these persons.'),
    delete_recordings: zod
        .boolean()
        .default(personsBulkDeleteCreateBodyDeleteRecordingsDefault)
        .describe('If true, queue deletion of all recordings associated with these persons.'),
    keep_person: zod
        .boolean()
        .default(personsBulkDeleteCreateBodyKeepPersonDefault)
        .describe('If true, keep the person records but delete their events and recordings.'),
})

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsCohortsRetrieveParams = () => 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 PersonsCohortsRetrieveQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
    person_id: zod.string().describe('The person ID or UUID to get cohorts for.'),
})

/**
 * This endpoint is meant for reading and deleting persons. To create or update persons, we recommend using the [capture API](https://posthog.com/docs/api/capture), the `$set` and `$unset` [properties](https://posthog.com/docs/product-analytics/user-properties), or one of our SDKs.
 */
export const PersonsValuesRetrieveParams = () => 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 PersonsValuesRetrieveQueryParams = () => zod.object({
    format: zod.enum(['csv', 'json']).optional(),
    key: zod.string().describe("The person property key to get values for (e.g., 'email', 'plan', 'role')."),
    value: zod
        .string()
        .optional()
        .describe('Optional search string to filter values (case-insensitive substring match).'),
})