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.

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

/**
 * Trust marks on warehouse tables and views. Reads exclude soft-deleted targets.
 */
export const DataCatalogCertificationsCreateParams = () => 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 dataCatalogCertificationsCreateBodyProposedStatusDefault = `certified`

export const DataCatalogCertificationsCreateBody = () => zod
    .object({
        table_id: zod.string().optional().describe('Warehouse table id to certify (XOR the other targets).'),
        saved_query_id: zod.string().optional().describe('Warehouse view (saved query) id to certify.'),
        table_name: zod.string().optional().describe('Queryable HogQL table name; 409 with candidates if ambiguous.'),
        view_name: zod.string().optional().describe('Queryable HogQL view name; 409 with candidates if ambiguous.'),
        notes: zod.string().optional().describe('Why this mark exists.'),
        proposed_status: zod
            .enum(['certified', 'deprecated'])
            .describe('\* `certified` - certified\n\* `deprecated` - deprecated')
            .default(dataCatalogCertificationsCreateBodyProposedStatusDefault)
            .describe(
                "Intent of the proposal: 'certified' to propose trusting this source, 'deprecated' to propose avoiding it (e.g. a stale or wrong source).\n\n\* `certified` - certified\n\* `deprecated` - deprecated"
            ),
    })
    .describe('Input for proposing a certification: address the target by id or (convenience) by name.')

/**
 * Mark the target as certified (prefer this source).
 */
export const DataCatalogCertificationsCertifyCreateParams = () => zod.object({
    id: zod.string().describe('A UUID string identifying this table certification.'),
    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\/."
        ),
})

/**
 * Mark the target as deprecated (avoid this source).
 */
export const DataCatalogCertificationsDeprecateCreateParams = () => zod.object({
    id: zod.string().describe('A UUID string identifying this table certification.'),
    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\/."
        ),
})

/**
 * CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).
 */
export const DataCatalogMetricsListParams = () => 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 DataCatalogMetricsListQueryParams = () => zod.object({
    definition_kind: zod.string().optional().describe('Only metrics with this query node kind.'),
    limit: zod.number().optional().describe('Number of results to return per page.'),
    offset: zod.number().optional().describe('The initial index from which to return the results.'),
    search: zod.string().optional().describe('A search term.'),
    status: zod.string().optional().describe('Only metrics with this review status.'),
})

/**
 * Create a metric. When a live metric already holds the name, returns 409 unless overwrite is true, in which case the existing metric is refined with the fields sent.
 */
export const DataCatalogMetricsCreateParams = () => 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 dataCatalogMetricsCreateBodyNameMax = 128

export const dataCatalogMetricsCreateBodyNameRegExp = new RegExp('^[A-Za-z][A-Za-z0-9_]\*$')
export const dataCatalogMetricsCreateBodyDisplayNameMax = 255

export const dataCatalogMetricsCreateBodyDescriptionMax = 300

export const dataCatalogMetricsCreateBodyUnitMax = 64

export const dataCatalogMetricsCreateBodySourceInsightShortIdMax = 12

export const dataCatalogMetricsCreateBodyAiModelMax = 128

export const dataCatalogMetricsCreateBodyConfidenceMin = 0
export const dataCatalogMetricsCreateBodyConfidenceMax = 1

export const dataCatalogMetricsCreateBodyOverwriteDefault = false

export const DataCatalogMetricsCreateBody = () => zod
    .object({
        name: zod
            .string()
            .max(dataCatalogMetricsCreateBodyNameMax)
            .regex(dataCatalogMetricsCreateBodyNameRegExp)
            .describe(
                "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."
            ),
        display_name: zod
            .string()
            .max(dataCatalogMetricsCreateBodyDisplayNameMax)
            .optional()
            .describe('Human-friendly label. Mutable, unlike name.'),
        description: zod
            .string()
            .max(dataCatalogMetricsCreateBodyDescriptionMax)
            .describe(
                "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."
            ),
        unit: zod
            .string()
            .max(dataCatalogMetricsCreateBodyUnitMax)
            .optional()
            .describe('Unit of the result, e.g. usd, percent, cents.'),
        owner: zod
            .email()
            .nullish()
            .describe(
                "Email of the human accountable for this metric, or null. Set it to the email of a member of this organization to reassign the metric, or to null to clear it. Changing the owner keeps the metric's approval."
            ),
        definition: zod
            .record(zod.string(), zod.unknown())
            .nullish()
            .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),
        source_insight_short_id: zod
            .string()
            .max(dataCatalogMetricsCreateBodySourceInsightShortIdMax)
            .nullish()
            .describe(
                "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."
            ),
        ai_model: zod
            .string()
            .max(dataCatalogMetricsCreateBodyAiModelMax)
            .optional()
            .describe('Model that generated the metric, if AI-authored.'),
        confidence: zod
            .number()
            .min(dataCatalogMetricsCreateBodyConfidenceMin)
            .max(dataCatalogMetricsCreateBodyConfidenceMax)
            .nullish()
            .describe("AI author's confidence in the proposal, 0-1."),
        reasoning: zod
            .string()
            .optional()
            .describe(
                'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'
            ),
        overwrite: zod
            .boolean()
            .default(dataCatalogMetricsCreateBodyOverwriteDefault)
            .describe(
                "Replace the fields of the live metric that already holds this name. When false, a taken name returns 409 with code 'metric_name_taken' and the existing metric stays unchanged. Overwriting an approved metric with a changed name, description, unit, or definition resets it to 'proposed'."
            ),
    })
    .describe(
        'Create input. ``overwrite`` exists only here, because PATCH addresses an existing metric by its URL name.'
    )

/**
 * CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).
 */
export const DataCatalogMetricsRetrieveParams = () => zod.object({
    name: 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\/."
        ),
})

/**
 * CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).
 */
export const DataCatalogMetricsPartialUpdateParams = () => zod.object({
    name: 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\/."
        ),
})

export const dataCatalogMetricsPartialUpdateBodyNameMax = 128

export const dataCatalogMetricsPartialUpdateBodyNameRegExp = new RegExp('^[A-Za-z][A-Za-z0-9_]\*$')
export const dataCatalogMetricsPartialUpdateBodyDisplayNameMax = 255

export const dataCatalogMetricsPartialUpdateBodyDescriptionMax = 300

export const dataCatalogMetricsPartialUpdateBodyUnitMax = 64

export const dataCatalogMetricsPartialUpdateBodySourceInsightShortIdMax = 12

export const dataCatalogMetricsPartialUpdateBodyAiModelMax = 128

export const dataCatalogMetricsPartialUpdateBodyConfidenceMin = 0
export const dataCatalogMetricsPartialUpdateBodyConfidenceMax = 1

export const DataCatalogMetricsPartialUpdateBody = () => zod.object({
    name: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodyNameMax)
        .regex(dataCatalogMetricsPartialUpdateBodyNameRegExp)
        .optional()
        .describe(
            "Identifier-safe run handle, unique among the team's live metrics. Renaming or deleting a metric frees its name for reuse, and anything referencing the old name (SQL over information_schema.metrics, run URLs, links) stops resolving."
        ),
    display_name: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodyDisplayNameMax)
        .optional()
        .describe('Human-friendly label. Mutable, unlike name.'),
    description: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodyDescriptionMax)
        .optional()
        .describe(
            "What the number is, in 1-2 short sentences under 300 characters: its meaning and grain plus any inclusion or exclusion that changes it. Leave out source tables or views, lineage, column lists, and comparisons with other metrics. Never narrate the query - the definition carries the mechanics; put the query's design decisions in 'reasoning'."
        ),
    unit: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodyUnitMax)
        .optional()
        .describe('Unit of the result, e.g. usd, percent, cents.'),
    owner: zod
        .email()
        .nullish()
        .describe(
            "Email of the human accountable for this metric, or null. Set it to the email of a member of this organization to reassign the metric, or to null to clear it. Changing the owner keeps the metric's approval."
        ),
    definition: zod
        .record(zod.string(), zod.unknown())
        .nullish()
        .describe('Machine-readable query. Omit for a name+description-only stub. Stored upgrade-canonical.'),
    source_insight_short_id: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodySourceInsightShortIdMax)
        .nullish()
        .describe(
            "Create the metric from this insight's query (snapshotted server-side). Set to null to unlink. Mutually exclusive with definition."
        ),
    ai_model: zod
        .string()
        .max(dataCatalogMetricsPartialUpdateBodyAiModelMax)
        .optional()
        .describe('Model that generated the metric, if AI-authored.'),
    confidence: zod
        .number()
        .min(dataCatalogMetricsPartialUpdateBodyConfidenceMin)
        .max(dataCatalogMetricsPartialUpdateBodyConfidenceMax)
        .nullish()
        .describe("AI author's confidence in the proposal, 0-1."),
    reasoning: zod
        .string()
        .optional()
        .describe(
            'Why the definition is shaped this way, in 1-3 short sentences. Name the main design decisions and trade-offs: the source table or view, a filter or exclusion, the grain, an approximation. Leave out the use case, who asked, run results, validation figures, and edit history.'
        ),
})

/**
 * CRUD for catalog metrics, addressed by their ``name`` (e.g. /metrics/mrr/).
 */
export const DataCatalogMetricsDestroyParams = () => zod.object({
    name: 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\/."
        ),
})

/**
 * Bless a metric as canonical. Returns 409 while the metric is drifted from its insight.
 */
export const DataCatalogMetricsApproveCreateParams = () => zod.object({
    name: 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\/."
        ),
})

export const DataCatalogMetricsApproveCreateBody = () => zod
    .object({
        expected_updated_at: zod.iso
            .datetime({ offset: true })
            .optional()
            .describe(
                "The metric's `updated_at` as last seen by the approver. When the metric changed since then, the API returns 409 and leaves it proposed. Omit to approve the current version."
            ),
    })
    .describe('Input for approving one metric.')

/**
 * Re-snapshot the linked insight's current query into the definition.
 */
export const DataCatalogMetricsRefreshFromInsightCreateParams = () => zod.object({
    name: 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\/."
        ),
})

/**
 * Execute the metric's definition and return the normalized result envelope.
 */
export const DataCatalogMetricsRunCreateParams = () => zod.object({
    name: 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\/."
        ),
})

export const DataCatalogMetricsRunCreateQueryParams = () => zod.object({
    refresh: zod
        .enum(['blocking', 'async', 'lazy_async', 'force_blocking', 'force_async', 'force_cache'])
        .optional()
        .describe(
            'Cache\/execution behavior, same semantics as \/query\/. Omit to serve a fresh cache hit and calculate blocking when stale.\n\n\* `blocking` - blocking\n\* `async` - async\n\* `lazy_async` - lazy_async\n\* `force_blocking` - force_blocking\n\* `force_async` - force_async\n\* `force_cache` - force_cache'
        ),
})

export const dataCatalogMetricsRunCreateBodyOffsetMin = 0

export const DataCatalogMetricsRunCreateBody = () => zod
    .object({
        date_from: zod
            .string()
            .optional()
            .describe(
                "Override the start of the query window (e.g. '-7d'). Rejected for HogQLQuery metrics, whose window is fixed in SQL."
            ),
        date_to: zod.string().optional().describe('Override the end of the query window.'),
        interval: zod
            .enum(['second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'])
            .describe(
                '\* `second` - second\n\* `minute` - minute\n\* `hour` - hour\n\* `day` - day\n\* `week` - week\n\* `month` - month\n\* `quarter` - quarter\n\* `year` - year'
            )
            .optional()
            .describe(
                'Override the bucket interval. Rejected for HogQLQuery metrics.\n\n\* `second` - second\n\* `minute` - minute\n\* `hour` - hour\n\* `day` - day\n\* `week` - week\n\* `month` - month\n\* `quarter` - quarter\n\* `year` - year'
            ),
        offset: zod
            .number()
            .min(dataCatalogMetricsRunCreateBodyOffsetMin)
            .optional()
            .describe(
                'Rows to skip, to read the page after a run that returned has_more. Pass next_offset from that run. Only HogQLQuery metrics accept it. Runs made with a personal or project API key are rejected.'
            ),
        query_id: zod.string().optional().describe('Client-supplied id to correlate or cancel the run.'),
    })
    .describe('Optional run-time overrides. The whole body may be omitted; a metric runs by its URL name.')

/**
 * Reviewed join facts. Accepting one promotes it to a real DataWarehouseJoin; rejections persist.
 */
export const DataCatalogRelationshipProposalsCreateParams = () => 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 dataCatalogRelationshipProposalsCreateBodySourceTableNameMax = 400

export const dataCatalogRelationshipProposalsCreateBodySourceTableKeyMax = 400

export const dataCatalogRelationshipProposalsCreateBodyJoiningTableNameMax = 400

export const dataCatalogRelationshipProposalsCreateBodyJoiningTableKeyMax = 400

export const dataCatalogRelationshipProposalsCreateBodyFieldNameMax = 400

export const dataCatalogRelationshipProposalsCreateBodyConfidenceMin = 0
export const dataCatalogRelationshipProposalsCreateBodyConfidenceMax = 1

export const DataCatalogRelationshipProposalsCreateBody = () => zod.object({
    source_table_name: zod
        .string()
        .max(dataCatalogRelationshipProposalsCreateBodySourceTableNameMax)
        .describe('Name of the table the join starts from.'),
    source_table_key: zod
        .string()
        .max(dataCatalogRelationshipProposalsCreateBodySourceTableKeyMax)
        .describe('HogQL key expression on the source table (casts allowed).'),
    joining_table_name: zod
        .string()
        .max(dataCatalogRelationshipProposalsCreateBodyJoiningTableNameMax)
        .describe('Name of the table being joined in.'),
    joining_table_key: zod
        .string()
        .max(dataCatalogRelationshipProposalsCreateBodyJoiningTableKeyMax)
        .describe('HogQL key expression on the joining table (casts allowed).'),
    field_name: zod
        .string()
        .max(dataCatalogRelationshipProposalsCreateBodyFieldNameMax)
        .describe('Accessor the join adds to the source table.'),
    configuration: zod.unknown().optional().describe('Extra join configuration, e.g. a field mapping.'),
    confidence: zod
        .number()
        .min(dataCatalogRelationshipProposalsCreateBodyConfidenceMin)
        .max(dataCatalogRelationshipProposalsCreateBodyConfidenceMax)
        .nullish()
        .describe('Discovery confidence in this join, 0-1.'),
    reasoning: zod.string().optional().describe('Why this join is proposed.'),
    evidence: zod.unknown().optional().describe('Sampling evidence: match rates, sample values.'),
})

/**
 * Promote the proposal to a real warehouse join after re-validating and probing it.
 */
export const DataCatalogRelationshipProposalsAcceptCreateParams = () => zod.object({
    id: zod.string().describe('A UUID string identifying this relationship proposal.'),
    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\/."
        ),
})

/**
 * Reject the proposal. Persists forever so the pair is never re-proposed.
 */
export const DataCatalogRelationshipProposalsRejectCreateParams = () => zod.object({
    id: zod.string().describe('A UUID string identifying this relationship proposal.'),
    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 DataCatalogRelationshipProposalsRejectCreateBody = () => zod.object({
    rejection_reason: zod
        .string()
        .optional()
        .describe('Why the proposal is rejected. Persisted so it is never re-proposed.'),
})