: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AIObservabilityGetCostsSchema": {
"type": "object",
"properties": {
"projectId": {
"description": "Project ID. Defaults to the active project when omitted.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"days": {
"type": "number"
}
}
},
"BillingSpendBreakdownsSchema": {
"description": "Dimensions to break spend down by. Pass `[\"type\"]` for per-product series, `[\"team\"]` for one series per project summed across products, or `[\"type\",\"team\"]` for per-project series within each product. Omit for one aggregate series.",
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": ["type", "team"]
}
},
{
"type": "null"
}
]
},
"BillingTeamIdsSchema": {
"description": "Project IDs to filter by, e.g. `[1,2]`. Omit for every project this request can see: all organization projects for full billing access, or the member-visible and token-scoped projects for member read-only access.",
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"type": "null"
}
]
},
"BillingUsageBreakdownsSchema": {
"description": "Dimensions to break usage down by. Pass `[\"type\"]` for per-usage-type series or `[\"type\",\"team\"]` for per-project series within each usage type. Team breakdowns require `\"type\"`; do not pass `[\"team\"]` by itself. Omit for one aggregate series.",
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": ["type", "team"]
}
},
{
"type": "null"
}
]
},
"BillingUsageTypesSchema": {
"description": "Array of usage type identifiers to filter on. Valid values: event_count_in_period, exceptions_captured_in_period, recording_count_in_period, rows_synced_in_period, free_historical_rows_synced_in_period, survey_responses_count_in_period, mobile_recording_count_in_period, mobile_billable_recording_count_in_period, billable_feature_flag_requests_count_in_period, enhanced_persons_event_count_in_period, ai_event_count_in_period, cdp_billable_invocations_in_period, rows_exported_in_period, ai_credits_used_in_period, signals_credits_used_in_period, signals_spend_credits_used_in_period, posthog_code_credits_used_in_period, posthog_code_token_credits_used_in_period, sandbox_compute_credits_used_in_period, sandbox_compute_cpu_millicore_seconds_in_period, sandbox_compute_memory_mib_seconds_in_period, workflow_emails_sent_in_period, workflow_billable_invocations_in_period, logs_and_traces_mb_in_period, logs_mb_in_period, apm_tracing_mb_in_period, logs_retention_30d_mb_in_period, logs_retention_mb_days_in_period, replay_vision_credits_used_in_period, data_pipelines, group_analytics. E.g. [\"event_count_in_period\",\"recording_count_in_period\"]. Omit for all types.",
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
]
},
"BusinessKnowledgeUrlSourceCreateSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "Short human label for the source. Shown in the settings list and in agent citations."
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri",
"description": "Public HTTP(S) URL to fetch. Private or internal hosts are rejected."
},
"source_type": {
"default": "url",
"description": "Source type. Always \"url\" for this tool.",
"type": "string",
"const": "url"
},
"refresh_interval": {
"default": "manual",
"description": "How often to auto-refresh this source in the background. Defaults to \"manual\" (no auto-refresh).",
"type": "string",
"enum": ["manual", "1h", "6h", "24h", "7d"]
},
"always_include": {
"default": false,
"description": "When true, this source's content is injected into every support reply prompt as general context (tone, policies, direction), not just when it matches a query.",
"type": "boolean"
}
},
"required": ["name", "url"]
},
"CanvasStateKeysOnlySchema": {
"default": true,
"type": "boolean"
},
"CanvasStateReadLimitSchema": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
},
"ChannelInstructionsBaseVersionSchema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Version returned by channel-instructions-retrieve. Use 0 when the channel has no instructions."
},
"DashboardInsightTileIdsSchema": {
"description": "IDs from tiles[].id in dashboard-get. Omit to run all insight tiles. Text and widget tiles produce no insight result.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"DashboardTileCreateSchema": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Dashboard ID. Use dashboard-get or dashboards-get-all to find it."
},
"type": {
"type": "string",
"enum": ["text", "image"],
"description": "Tile type. Use text for Markdown content. Use image for a body with exactly one Markdown image."
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "Markdown body. For image, provide exactly one Markdown image. For text, provide Markdown content that is not an image-only body."
},
"agent_context": {
"description": "Optional context for AI agents, such as semantic layer metric references, data sources, tile-specific query assumptions, caveats, or editing guidance. Keep canonical metric definitions in the semantic layer. An empty string or null means there is no agent context. Shared and exported dashboards, and organizations without AI data processing approval, omit this field. Max 10000 characters.",
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
]
},
"layouts": {
"description": "Optional dashboard-grid layout for desktop (sm) and mobile (xs).",
"type": "object",
"properties": {
"sm": {
"description": "Layout for the standard (desktop) breakpoint. The grid is 12 columns wide.",
"type": "object",
"properties": {
"x": {
"description": "Column position in the dashboard grid (0-indexed).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"y": {
"description": "Row position in the dashboard grid (0-indexed).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"w": {
"description": "Width in grid columns. The desktop grid is 12 columns wide.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"h": {
"description": "Height in grid rows.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
},
"xs": {
"description": "Layout for the small (mobile) breakpoint. The grid is 1 column wide.",
"type": "object",
"properties": {
"x": {
"description": "Column position in the dashboard grid (0-indexed).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"y": {
"description": "Row position in the dashboard grid (0-indexed).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"w": {
"description": "Width in grid columns. The desktop grid is 12 columns wide.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"h": {
"description": "Height in grid rows.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
}
}
}
},
"color": {
"description": "Optional tile accent color.",
"anyOf": [
{
"type": "string",
"maxLength": 400
},
{
"type": "null"
}
]
}
},
"required": ["id", "type", "body"]
},
"DebugMcpUiAppsSchema": {
"type": "object",
"properties": {
"message": {
"description": "Optional message to include in the debug data",
"type": "string"
}
}
},
"EmailTemplateDesignPatchSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The email template id to edit."
},
"operations": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_content"
},
"id": {
"type": "string",
"description": "Id of the content block to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial content-block fields, deep-merged into the existing block; a null leaf deletes that key. e.g. {values: {text: '<p>Hi</p>'}} changes only the block's text."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_column"
},
"id": {
"type": "string",
"description": "Id of the column to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial column fields, deep-merged; a null leaf deletes that key."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_row"
},
"id": {
"type": "string",
"description": "Id of the row to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial row fields, deep-merged; a null leaf deletes that key."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_body"
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial body fields, deep-merged. e.g. {values: {backgroundColor: '#ffffff'}}."
}
},
"required": ["op", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_content"
},
"column_id": {
"type": "string",
"description": "Id of the column to insert the block into."
},
"content": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "A content block {type, values: {...}}; omit id and values._meta — they are assigned server-side. type is one of text, heading, button, image, divider, html, etc."
},
"index": {
"description": "0-based insert position; omit to append to the end.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "column_id", "content"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_content"
},
"id": {
"type": "string",
"description": "Id of the content block to remove."
}
},
"required": ["op", "id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "move_content"
},
"id": {
"type": "string",
"description": "Id of the content block to move."
},
"column_id": {
"type": "string",
"description": "Id of the destination column."
},
"index": {
"description": "0-based position in the destination column; omit to append.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "id", "column_id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_row"
},
"row": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "A full row {cells, columns: [{contents: [...], values}], values}; ids and Unlayer numbering are assigned server-side for the row and everything nested in it."
},
"index": {
"description": "0-based insert position; omit to append to the end.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "row"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_row"
},
"id": {
"type": "string",
"description": "Id of the row to remove."
}
},
"required": ["op", "id"],
"additionalProperties": false
}
]
},
"description": "Ordered edits applied atomically to the template's Unlayer design: the stored design is read, the ops are applied in order, the result is validated and re-rendered to HTML, and saved only if valid — otherwise the template is left unchanged. Reference blocks by id so you never resend the whole design."
}
},
"required": ["id", "operations"],
"additionalProperties": false
},
"EventDefinitionCreateSchema": {
"type": "object",
"properties": {
"eventName": {
"type": "string",
"minLength": 1,
"maxLength": 400,
"description": "The name of the event to create (e.g. \"user_signed_up\")"
},
"data": {
"description": "Optional metadata for the new event definition",
"type": "object",
"properties": {
"description": {
"description": "Description explaining when the event is triggered",
"type": "string"
},
"owner": {
"description": "Numeric user ID of the person responsible for the event. Must be a member of the organization. To find the ID from an email, call `org-members-list` and use `user.id`. Pass null to remove the owner.",
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"tags": {
"description": "Tags to organize events by product area (e.g. \"checkout\", \"onboarding\") or user journey stage (e.g. \"acquisition\", \"activation\", \"monetization\", \"retention\")",
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"verified": {
"description": "Mark as verified to indicate the event is properly instrumented and tracking correctly",
"type": "boolean"
},
"hidden": {
"description": "Mark event as no longer used/captured. Hides it from UI while preserving historical data",
"type": "boolean"
}
}
}
},
"required": ["eventName"]
},
"EventDefinitionGetSchema": {
"type": "object",
"properties": {
"eventName": {
"type": "string",
"minLength": 1,
"description": "The exact name of the event (e.g. \"$pageview\", \"user_signed_up\")"
}
},
"required": ["eventName"]
},
"EventDefinitionUpdateInputSchema": {
"type": "object",
"properties": {
"description": {
"description": "Description explaining when the event is triggered",
"type": "string"
},
"owner": {
"description": "Numeric user ID of the person responsible for the event. Must be a member of the organization. To find the ID from an email, call `org-members-list` and use `user.id`. Pass null to remove the owner.",
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"tags": {
"description": "Tags to organize events by product area (e.g. \"checkout\", \"onboarding\") or user journey stage (e.g. \"acquisition\", \"activation\", \"monetization\", \"retention\")",
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"verified": {
"description": "Mark as verified to indicate the event is properly instrumented and tracking correctly",
"type": "boolean"
},
"hidden": {
"description": "Mark event as no longer used/captured. Hides it from UI while preserving historical data",
"type": "boolean"
}
}
},
"EventDefinitionUpdateSchema": {
"type": "object",
"properties": {
"eventName": {
"type": "string",
"description": "The name of the event to update (e.g. \"$pageview\", \"user_signed_up\")"
},
"data": {
"type": "object",
"properties": {
"description": {
"description": "Description explaining when the event is triggered",
"type": "string"
},
"owner": {
"description": "Numeric user ID of the person responsible for the event. Must be a member of the organization. To find the ID from an email, call `org-members-list` and use `user.id`. Pass null to remove the owner.",
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"tags": {
"description": "Tags to organize events by product area (e.g. \"checkout\", \"onboarding\") or user journey stage (e.g. \"acquisition\", \"activation\", \"monetization\", \"retention\")",
"type": "array",
"items": {
"type": "string",
"maxLength": 255
}
},
"verified": {
"description": "Mark as verified to indicate the event is properly instrumented and tracking correctly",
"type": "boolean"
},
"hidden": {
"description": "Mark event as no longer used/captured. Hides it from UI while preserving historical data",
"type": "boolean"
}
},
"description": "The event definition data to update"
}
},
"required": ["eventName", "data"]
},
"ExecuteSQLSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "The final SQL query to be executed."
},
"context": {
"description": "Why this query runs, and the governed-catalog outcome behind it: state \"governed catalog consulted: no match\" here when no approved metric covered the measure. This rides alongside the query and never reaches the person who asked, so catalog bookkeeping belongs here instead of in the answer.",
"type": "string"
},
"truncate": {
"default": true,
"description": "Whether to truncate large blob/JSON values in results. Defaults to true. Set to false when you need full untruncated results (e.g., for dumping to a file).",
"type": "boolean"
},
"connectionId": {
"description": "Optional id of a data warehouse connection (e.g. Postgres, MySQL, Snowflake, Redshift). When set, the query runs live against that source instead of the ClickHouse catalog, and may only reference that source's tables. Discover connection ids with external-data-sources-connections-list, then list a connection's tables by running `SELECT table_name FROM system.information_schema.tables` with that connectionId set.",
"type": "string"
},
"sendRawQuery": {
"description": "Send `query` to the connection verbatim instead of compiling it from HogQL first. Use this for SQL only that connection's own engine understands, such as vendor-specific functions. Requires connectionId, and works only on a pure direct connection (access_method 'direct'), not on a synced source with live queries enabled. The connection is read-only and accepts a single statement.",
"type": "boolean"
}
},
"required": ["query"]
},
"ExperimentResultsGetSchema": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The ID of the experiment to get comprehensive results for"
},
"refresh": {
"default": false,
"description": "Asks for a blocking calculation. A cached result younger than 24 hours is still returned, so this does not force a recomputation. Defaults to false.",
"type": "boolean"
}
},
"required": ["id"]
},
"ExperimentVariantNotesSchema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
},
"description": "Free-text notes per variant, keyed by variant key, shown under each variant in the experiment view. Use them to document what each variant changes. On update, only the variants you pass change and the notes of other variants stay. Pass an empty string to clear the note of a variant."
},
"ExperimentVariantScreenshotMediaIdsSchema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Screenshot media IDs per variant, keyed by variant key, shown under each variant in the experiment view. Each value is the complete list of uploaded media IDs for that variant. To add a screenshot, upload the image with media-image-upload-start and media-image-upload-complete with purpose \"experiment\", then pass the returned id here. On update, only the variants you pass change and the screenshots of other variants stay. Pass an empty list to remove all screenshots of a variant."
},
"ExplainChartInputSchema": {
"type": "object",
"properties": {
"insightId": {
"description": "The saved insight to explain: its numeric `id` or 8-character `short_id`.",
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"query": {
"description": "A TrendsQuery to explain when the chart is not a saved insight. Pass this or `insightId`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"series": {
"default": 0,
"description": "Index of the series in the chart's results that the story follows. Defaults to the first one.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"headline": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "One sentence a person could read in place of the whole story. Name what stands out, with no numbers, and wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in **double asterisks**."
},
"chapters": {
"minItems": 1,
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "A short title, for example \"A spike on October 2\" or \"Lower since September 28\"."
},
"start": {
"type": "string",
"minLength": 1,
"description": "The first point the chapter covers, copied from the chart's `days` (for example `2026-10-02`, or `2026-10-02 14:00:00` on an hourly chart)."
},
"end": {
"description": "The last point the chapter covers, inclusive. Omit it when the chapter is about one point.",
"type": "string",
"minLength": 1
},
"summary": {
"description": "What happened, in one or two sentences. Do not repeat the chart's own numbers: the app works them out from the chart and shows them above this.",
"type": "string",
"maxLength": 400
},
"cause": {
"description": "The most likely cause, in one or two sentences. Say whether it is a real change in behavior or an artifact of the data. Wrap the name behind it, such as a referrer or a country, in **double asterisks**. Omit it when you found no cause.",
"type": "string",
"maxLength": 600
},
"confidence": {
"description": "How sure you are of the cause. high: independent signals agree. medium: one signal, or a strong pattern without a cross-check. low: a guess.",
"type": "string",
"enum": ["high", "medium", "low"]
},
"confidence_reason": {
"description": "Why you gave that confidence, in one sentence.",
"type": "string",
"maxLength": 200
},
"evidence": {
"description": "What you checked, at most 6 findings.",
"maxItems": 6,
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 400,
"description": "One finding in one sentence, with the numbers from the query that found it. Mark the name that matters with **double asterisks**."
},
"query": {
"description": "The query that found this, as you ran it. The explanation runs it again and draws the result beside the finding. An insight query (`TrendsQuery`, `FunnelsQuery`, `RetentionQuery`, `StickinessQuery`, `PathsQuery` or `LifecycleQuery`) draws with its insight chart. A `HogQLQuery` draws from its rows: select the x-axis column first (a time bucket or a label), then either the numbers to draw, or one text column to break down by followed by one number. Order by the x-axis column. SQL returns 100 rows unless it sets a `LIMIT`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"insightShortId": {
"description": "The `short_id` of a saved insight that shows this. The explanation links to it.",
"type": "string",
"pattern": "^[A-Za-z0-9]{8}$"
},
"url": {
"description": "A link to the GitHub pull request or commit behind this, when it is not a query or a saved insight. No other links are accepted.",
"type": "string",
"pattern": "^https:\\/\\/github\\.com\\/[A-Za-z0-9-]+\\/[A-Za-z0-9._-]+\\/(pull\\/\\d+|commit\\/[0-9a-fA-F]{7,40})\\/?$"
}
},
"required": ["text"]
}
}
},
"required": ["title", "start"]
},
"description": "The moments that stand out, in the order to read them. At most 8."
}
},
"required": ["headline", "chapters"]
},
"ExplainChartSaveInputSchema": {
"type": "object",
"properties": {
"insightId": {
"description": "The saved insight to explain: its numeric `id` or 8-character `short_id`.",
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"query": {
"description": "A TrendsQuery to explain when the chart is not a saved insight. Pass this or `insightId`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"series": {
"default": 0,
"description": "Index of the series in the chart's results that the story follows. Defaults to the first one.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"headline": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "One sentence a person could read in place of the whole story. Name what stands out, with no numbers, and wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in **double asterisks**."
},
"chapters": {
"minItems": 1,
"maxItems": 8,
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "A short title, for example \"A spike on October 2\" or \"Lower since September 28\"."
},
"start": {
"type": "string",
"minLength": 1,
"description": "The first point the chapter covers, copied from the chart's `days` (for example `2026-10-02`, or `2026-10-02 14:00:00` on an hourly chart)."
},
"end": {
"description": "The last point the chapter covers, inclusive. Omit it when the chapter is about one point.",
"type": "string",
"minLength": 1
},
"summary": {
"description": "What happened, in one or two sentences. Do not repeat the chart's own numbers: the app works them out from the chart and shows them above this.",
"type": "string",
"maxLength": 400
},
"cause": {
"description": "The most likely cause, in one or two sentences. Say whether it is a real change in behavior or an artifact of the data. Wrap the name behind it, such as a referrer or a country, in **double asterisks**. Omit it when you found no cause.",
"type": "string",
"maxLength": 600
},
"confidence": {
"description": "How sure you are of the cause. high: independent signals agree. medium: one signal, or a strong pattern without a cross-check. low: a guess.",
"type": "string",
"enum": ["high", "medium", "low"]
},
"confidence_reason": {
"description": "Why you gave that confidence, in one sentence.",
"type": "string",
"maxLength": 200
},
"evidence": {
"description": "What you checked, at most 6 findings.",
"maxItems": 6,
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 400,
"description": "One finding in one sentence, with the numbers from the query that found it. Mark the name that matters with **double asterisks**."
},
"query": {
"description": "The query that found this, as you ran it. The explanation runs it again and draws the result beside the finding. An insight query (`TrendsQuery`, `FunnelsQuery`, `RetentionQuery`, `StickinessQuery`, `PathsQuery` or `LifecycleQuery`) draws with its insight chart. A `HogQLQuery` draws from its rows: select the x-axis column first (a time bucket or a label), then either the numbers to draw, or one text column to break down by followed by one number. Order by the x-axis column. SQL returns 100 rows unless it sets a `LIMIT`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"insightShortId": {
"description": "The `short_id` of a saved insight that shows this. The explanation links to it.",
"type": "string",
"pattern": "^[A-Za-z0-9]{8}$"
},
"url": {
"description": "A link to the GitHub pull request or commit behind this, when it is not a query or a saved insight. No other links are accepted.",
"type": "string",
"pattern": "^https:\\/\\/github\\.com\\/[A-Za-z0-9-]+\\/[A-Za-z0-9._-]+\\/(pull\\/\\d+|commit\\/[0-9a-fA-F]{7,40})\\/?$"
}
},
"required": ["text"]
}
}
},
"required": ["title", "start"]
},
"description": "The moments that stand out, in the order to read them. At most 8."
},
"explanationId": {
"description": "The id an earlier `explain-chart-save` call on this chart returned, when you are fixing that explanation. Its link then shows the fix. Omit it for a new explanation.",
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": ["headline", "chapters"]
},
"ExternalDataJobsAfterSchema": {
"type": "string",
"description": "ISO timestamp — only return jobs created after this date (e.g. \"2025-01-01T00:00:00Z\")."
},
"ExternalDataJobsBeforeSchema": {
"type": "string",
"description": "ISO timestamp — only return jobs created before this date (e.g. \"2025-12-31T23:59:59Z\")."
},
"ExternalDataJobsSchemasSchema": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter jobs by table schema names (e.g. [\"users\", \"orders\"]). Only returns jobs for these tables."
},
"ExternalDataSourcePayloadSchema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Connection credentials for the source. Keys depend on source_type. For database sources: host, port, database, user, password, schema. For SaaS sources: api_key or OAuth fields. For source_type \"Custom\" (a user-defined REST API): `manifest_json` (a stringified RESTAPIConfig describing client.base_url, auth, and resources) plus the credential for the auth type declared in the manifest — `auth_token` (bearer), `auth_api_key` (api_key), or `auth_password` (http_basic); keep secrets in these auth_* keys, never inline in manifest_json. Use external-data-sources-wizard (pass source_type) to see required fields per source type. For the advanced external-data-sources-create flow, the per-table 'schemas' array (built from external-data-sources-db-schema) also goes in here, e.g. {\"host\": ..., \"password\": ..., \"schemas\": [{\"name\": \"orders\", \"should_sync\": true, \"sync_type\": \"incremental\", \"incremental_field\": \"updated_at\", \"incremental_field_type\": \"datetime\"}]}. That array is optional: omit it and every discovered table syncs with default settings. Do not pass unresolved {\"secretRef\": ...} objects — resolve secrets to real values first, or use a credential_id from data-warehouse-source-connect-link."
},
"ExternalDataSourceTypeSchema": {
"type": "string",
"description": "The source type name (e.g. \"Postgres\", \"MySQL\", \"Stripe\"). Use external-data-sources-wizard to see available types and their required fields."
},
"FeedbackSubmitSchema": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1,
"description": "A one-sentence headline capturing the feedback (e.g. \"session replay scrubber jumps backwards when you click the timeline\", \"query-trends descriptions made it hard to choose between trends and funnels\", or \"the new SQL editor autocomplete is excellent\")."
},
"feedback_type": {
"type": "string",
"enum": ["product", "mcp", "docs", "scout", "other"],
"description": "What this feedback is about. \"product\" = any PostHog product or feature (insights, session replay, feature flags, the data warehouse, web analytics, error tracking, etc.). \"mcp\" = this MCP server itself — a tool, its input schema, response format, an error, or these instructions. \"docs\" = PostHog documentation. \"scout\" = a canonical PostHog scout skill's content — reserved for scheduled scout runs reporting an improvement opportunity in their own PostHog-authored skill (set `scout_skill_name`, `scout_skill_version`, and `scout_category`). \"other\" = anything that doesn't fit the above."
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative", "mixed"],
"description": "The overall tone. Use \"negative\" for something broken or blocking, \"mixed\" for mostly-fine-but-with-a-concrete-problem, \"neutral\" for a suggestion or feature request with no strong sentiment, and \"positive\" for praise or something that worked well. All sentiments are welcome — positive feedback is encouraged, not just problems."
},
"product_area": {
"description": "The PostHog product or area this is about, in free text (e.g. \"session replay\", \"insights\", \"data warehouse\", \"feature flags\", \"docs\"). Most useful for product feedback; for MCP feedback the tool name belongs in `details`/`friction_points` instead.",
"type": "string"
},
"category": {
"description": "For MCP feedback (`feedback_type: \"mcp\"`) only: the single category that best describes the dominant theme. Pick \"missing_tool\" if a capability was absent, \"tool_description\" if the tool docs were unclear, \"tool_input_schema\" if input args were confusing, \"tool_output_format\" if the response was hard to consume, \"instructions_clarity\" if these MCP instructions were unclear, \"tool_correctness\" if a tool returned wrong data, \"error_message\" if an error was unhelpful, \"performance\" if latency was the issue. Omit for product, docs, or other feedback.",
"type": "string",
"enum": [
"tool_correctness",
"tool_description",
"tool_input_schema",
"tool_output_format",
"missing_tool",
"instructions_clarity",
"performance",
"error_message",
"other"
]
},
"scout_skill_name": {
"description": "For scout feedback (`feedback_type: \"scout\"`) only: the canonical scout skill the feedback is about (e.g. \"signals-scout-web-analytics\"), exactly as named in the run identity. Required for scout feedback — without it the feedback cannot be aggregated per skill.",
"type": "string"
},
"scout_skill_version": {
"description": "For scout feedback (`feedback_type: \"scout\"`) only: the skill version the run executed (from the run identity). Feedback is only actionable against the version that produced it — the skill may have moved since.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"scout_category": {
"description": "For scout feedback (`feedback_type: \"scout\"`) only: the single category that best describes the skill gap. \"false_positive\" = the skill's detection rules surfaced something that wasn't real; \"missed_detection\" = a real issue the skill's instructions steered you past; \"discriminator_gap\" = the skill's signal-vs-baseline discriminator doesn't hold for a class of projects; \"wasted_investigation\" = an investigation pattern the skill mandates burned budget without payoff; \"instruction_ambiguity\" = an instruction that is ambiguous in practice. Omit for non-scout feedback.",
"type": "string",
"enum": [
"false_positive",
"missed_detection",
"discriminator_gap",
"wasted_investigation",
"instruction_ambiguity",
"other"
]
},
"task_completed": {
"description": "Were you able to complete the user's task? Be honest — \"false\" is just as useful as \"true\". Most relevant when `feedback_type` is \"mcp\".",
"type": "boolean"
},
"tools_used": {
"description": "The MCP tool names you called while working on the user's task (e.g. [\"read-data-schema\", \"query-trends\"]). Helps us correlate feedback to specific tools.",
"type": "array",
"items": {
"type": "string"
}
},
"friction_points": {
"description": "Clear, concise bullet points describing the friction — what was confusing, broken, slow, or missing. Quote the exact product surface, tool name, parameter, or error text where you can. Omit for purely positive feedback.",
"type": "string"
},
"suggested_improvement": {
"description": "The single most impactful, concrete change that would address this feedback, if you can name one (e.g. \"add a `filters` example to query-funnel's description\", or \"let the replay scrubber snap to the nearest event\"). Optional — praise or an observation doesn't need one.",
"type": "string"
},
"user_request": {
"description": "A short, anonymised paraphrase of what the user originally asked you to do. Do not include PII, customer names, or sensitive query content.",
"type": "string"
},
"details": {
"description": "Any additional context that doesn't fit the other fields. Keep it to clear, concise bullet points.",
"type": "string"
}
},
"required": ["summary", "feedback_type", "sentiment"]
},
"FlagRulesV2UpdateInputSchema": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "A unique integer value identifying this feature flag."
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "The flag's top-level `version` from your latest read. The write is refused with 409 when the flag changed after it."
},
"filters": {
"type": "object",
"properties": {
"version": {
"type": "number",
"const": 2,
"description": "Config format. Always 2 here; unrelated to the top-level `version`."
},
"return_type": {
"type": "string",
"description": "Copy it from the flag you read. It cannot change."
},
"default_value": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Value served when no rule returns one. Must match `return_type`, or null."
},
"rules": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "The complete ordered rule list, in the shape the flag read returns. Keep `id` and `seed` on every rule you keep; omit both on a new rule."
}
},
"required": ["version", "return_type", "default_value", "rules"],
"additionalProperties": {},
"description": "The complete new configuration. It replaces the stored `filters`."
}
},
"required": ["id", "version", "filters"]
},
"InsightQueryInputSchema": {
"type": "object",
"properties": {
"insightId": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
],
"description": "The insight to run: its numeric `id` or 8-character `short_id`."
},
"output_format": {
"default": "optimized",
"description": "Output format. \"optimized\" returns a human-readable summary from server-side formatters (recommended for analysis). \"json\" returns the raw query results as JSON.",
"type": "string",
"enum": ["optimized", "json"]
},
"variables_override": {
"description": "Object (or pre-encoded JSON string) to override the insight's HogQL variables for this run only (not persisted). Format: {\"<variable_id>\": {\"code_name\": \"<code_name>\", \"variableId\": \"<variable_id>\", \"value\": <new_value>}}. Each entry must include `code_name` — partial entries are silently dropped. The simplest workflow is to call `insight-get` first, copy the matching entry from the response's query variables, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token.",
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
]
},
"filters_override": {
"description": "Object (or pre-encoded JSON string) to override the insight's filters for this run only (not persisted). Top-level keys replace; nested values are not deep-merged — pass the complete value for any key you override. Accepted keys: `date_from`, `date_to`, `explicitDate`, `interval`, `properties`, `filterTestAccounts`, `breakdown_filter`, `compareFilter`, `metricVariables`. Other keys (for example `display`, `dateRange`, `filter_test_accounts` or `compare`) are rejected. Ignored when accessed via a sharing token.",
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
]
}
},
"required": ["insightId"]
},
"OfflineExperimentUploadItemsSchema": {
"description": "Complete immutable declarations for referenced items. Omit existing items to reuse them without a payload.",
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Caller-generated UUID for one input/output execution. Reuse for exact retries."
},
"model_version": {
"description": "Model used for this item. Omitted or null values inherit the experiment's model.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"case_key": {
"description": "Stable case identifier for matching inputs across experiments.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"trial": {
"description": "Identifier for a repeated execution of the same case.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"dataset_item_identifier": {
"description": "Stable item identifier in an external dataset.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"dataset_item_version_identifier": {
"description": "Pinned item-version identifier in an external dataset.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"dataset_item_version_id": {
"description": "UUID of the hosted item version in the experiment's dataset revision.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"application_trace_id": {
"description": "Trace identifier for the application execution that produced this output.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"payload": {
"description": "Optional input/output payload, up to 1 MiB and 32 JSON levels. Omission, {} and null properties differ.",
"type": "object",
"properties": {
"input": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"output": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"expected_output": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"metadata": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"required": ["id"]
}
},
"OfflineExperimentUploadResultsSchema": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"item_id": {
"type": "string",
"description": "UUID of an item declared in this request or already accepted in this experiment."
},
"scorer_version_id": {
"type": "string",
"description": "Exact UUID of an existing scorer version in this project."
},
"status": {
"type": "string",
"enum": ["ok", "error", "skipped", "not_applicable"],
"description": "Outcome of this scorer execution.\n\n* `ok` - OK\n* `error` - Error\n* `skipped` - Skipped\n* `not_applicable` - Not applicable"
},
"value": {
"description": "Required for ok: finite number, boolean, or distinct category keys matching the scorer version.",
"anyOf": [
{
"type": "number"
},
{
"type": "boolean"
},
{
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"maxLength": 128
}
},
{
"type": "null"
}
]
},
"error_code": {
"description": "Optional stable error code, permitted only for error outcomes.",
"anyOf": [
{
"type": "string",
"maxLength": 128
},
{
"type": "null"
}
]
},
"evaluator_trace_id": {
"description": "Trace identifier of the evaluator that produced this result.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"evaluated_at": {
"description": "Caller-supplied evaluation time in ISO 8601 format.",
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"payload": {
"description": "Optional reasoning, error message, and metadata, up to 256 KiB and 32 JSON levels.",
"type": "object",
"properties": {
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"required": ["item_id", "scorer_version_id", "status"]
},
"description": "One to 1,000 unique item/scorer-version results. The entire request commits atomically."
},
"OrganizationGetAllSchema": {
"type": "object",
"properties": {}
},
"OrganizationSetActiveSchema": {
"anyOf": [
{
"type": "object",
"properties": {
"orgId": {
"type": "string",
"description": "The organization to switch to: the `id` returned by `organizations-get` (a UUID-like string, not the organization name). Use `organizations-get` to resolve a name to its id."
}
},
"required": ["orgId"]
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alias for `orgId`. Accepts the `id` returned by `organizations-list` / `organization-get`."
}
},
"required": ["id"]
},
{
"type": "object",
"properties": {
"organizationId": {
"type": "string",
"description": "Alias for `orgId`. Accepts the `id` returned by `organizations-list` / `organization-get`."
}
},
"required": ["organizationId"]
},
{
"type": "object",
"properties": {
"organization_id": {
"type": "string",
"description": "Alias for `orgId`. Accepts the `id` returned by `organizations-list` / `organization-get`."
}
},
"required": ["organization_id"]
},
{
"type": "object",
"properties": {
"org_id": {
"type": "string",
"description": "Alias for `orgId`. Accepts the `id` returned by `organizations-list` / `organization-get`."
}
},
"required": ["org_id"]
}
]
},
"PathCleaningRulesUpdateSchema": {
"type": "object",
"properties": {
"operations": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "append"
},
"alias": {
"type": "string",
"description": "The replacement for the matched path, e.g. \"/users/<id>/profile\". Default to angle-bracket placeholders (<id>, <uuid>, <slug>) by convention. An empty string is valid: it deletes the matched text (e.g. to strip a \"?page=N\" fragment). The alias can also reference a regex capture group with ClickHouse replaceRegexpAll syntax (\"\\1\" to \"\\9\" for a group, \"\\0\" for the whole match), but a rule with capture groups is roughly 3x more expensive per row, so only use one when it collapses several near-identical rules into one."
},
"regex": {
"type": "string",
"minLength": 1,
"description": "A re2 pattern matched against the path, e.g. \"/users/\\\\d+/profile\". No need to escape \"/\". Anchor with ^ / $ when you mean it."
}
},
"required": ["action", "alias", "regex"],
"description": "Add a new rule at the end of the ordered list (runs last)."
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "insert"
},
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Zero-based position to insert the rule at. Existing rules shift down."
},
"alias": {
"type": "string",
"description": "The replacement for the matched path, e.g. \"/users/<id>/profile\". Default to angle-bracket placeholders (<id>, <uuid>, <slug>) by convention. An empty string is valid: it deletes the matched text (e.g. to strip a \"?page=N\" fragment). The alias can also reference a regex capture group with ClickHouse replaceRegexpAll syntax (\"\\1\" to \"\\9\" for a group, \"\\0\" for the whole match), but a rule with capture groups is roughly 3x more expensive per row, so only use one when it collapses several near-identical rules into one."
},
"regex": {
"type": "string",
"minLength": 1,
"description": "A re2 pattern matched against the path, e.g. \"/users/\\\\d+/profile\". No need to escape \"/\". Anchor with ^ / $ when you mean it."
}
},
"required": ["action", "index", "alias", "regex"],
"description": "Insert a new rule at a specific position — use when it must run before more general rules."
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "replace"
},
"target_alias": {
"type": "string",
"description": "The alias of the existing rule to target (must match an existing rule exactly). Use \"\" to target a rule whose alias is empty."
},
"alias": {
"description": "New alias. Omit to keep the current alias.",
"type": "string"
},
"regex": {
"description": "New regex. Omit to keep the current regex.",
"type": "string",
"minLength": 1
}
},
"required": ["action", "target_alias"],
"description": "Replace the alias and/or regex of an existing rule, keeping its position."
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "remove"
},
"target_alias": {
"type": "string",
"description": "The alias of the existing rule to target (must match an existing rule exactly). Use \"\" to target a rule whose alias is empty."
}
},
"required": ["action", "target_alias"],
"description": "Remove an existing rule by alias."
},
{
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "reorder"
},
"ordered_aliases": {
"type": "array",
"items": {
"type": "string"
},
"description": "The full set of current aliases in the new desired order (including \"\" for any empty-alias rule and any duplicates). Must be a permutation of the existing aliases."
}
},
"required": ["action", "ordered_aliases"],
"description": "Reorder the existing rules. Order matters: rules apply sequentially, each feeding the next."
}
]
},
"description": "Ordered list of edits to apply to the current path cleaning rules, in sequence."
},
"sample_paths": {
"description": "Optional real paths (e.g. \"/users/123/profile\") to preview against, up to 25. The response shows how the resulting rule set rewrites each one. Approximate (JS regex, not re2) — use execute-sql with replaceRegexpAll to confirm edge cases.",
"maxItems": 25,
"type": "array",
"items": {
"type": "string",
"maxLength": 2048
}
},
"confirm": {
"default": false,
"description": "Must be true to persist. When false (default) the tool returns a preview of the resulting rules (and any sample-path rewrites) WITHOUT saving — surface it to the user, then re-run with confirm:true.",
"type": "boolean"
}
},
"required": ["operations"]
},
"ProjectGetAllSchema": {
"type": "object",
"properties": {}
},
"ProjectSetActiveSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": ["projectId"]
},
"PromptListInputSchema": {
"type": "object",
"properties": {
"search": {
"description": "Optional substring filter applied to prompt names and prompt content.",
"type": "string"
},
"label": {
"description": "Return each prompt at the version this label points to, e.g. 'production'. Prompts that do not carry the label are omitted. If omitted, the latest version of every prompt is returned.",
"type": "string",
"minLength": 1,
"maxLength": 128
},
"content": {
"default": "none",
"description": "Controls how much prompt content is included in list results. 'full' includes the full prompt, 'preview' includes a short prompt_preview, and 'none' omits prompt content entirely.",
"type": "string",
"enum": ["full", "preview", "none"]
}
}
},
"PropertyDefinitionUpdateInputSchema": {
"type": "object",
"properties": {
"description": {
"description": "Description explaining what the property represents",
"type": "string"
},
"tags": {
"description": "Tags to organize properties by product area (e.g. \"checkout\", \"onboarding\") or user journey stage (e.g. \"acquisition\", \"activation\", \"monetization\", \"retention\"). Warning: this REPLACES the property's entire tag list, it does not merge. To keep existing tags, include them alongside the new ones; to remove a tag, omit it. Omit this field entirely to leave tags unchanged.",
"type": "array",
"items": {
"type": "string"
}
},
"property_type": {
"description": "The data type of the property. Controls how the property is parsed, displayed, and filtered.",
"type": "string",
"enum": ["DateTime", "String", "Numeric", "Boolean", "Duration"]
},
"verified": {
"description": "Mark as verified to indicate the property is correctly instrumented and safe to use",
"type": "boolean"
},
"hidden": {
"description": "Mark property as no longer used. Hides it from the UI while preserving historical data",
"type": "boolean"
}
}
},
"PropertyDefinitionUpdateSchema": {
"type": "object",
"properties": {
"propertyName": {
"type": "string",
"description": "The exact name of the property to update (e.g. \"$browser\", \"plan_type\")"
},
"type": {
"default": "event",
"description": "Which property taxonomy the property belongs to. Defaults to \"event\" (event properties).",
"type": "string",
"enum": ["event", "person", "group", "session"]
},
"groupTypeIndex": {
"description": "Required when type is \"group\": the zero-based index of the group type the property belongs to.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"data": {
"type": "object",
"properties": {
"description": {
"description": "Description explaining what the property represents",
"type": "string"
},
"tags": {
"description": "Tags to organize properties by product area (e.g. \"checkout\", \"onboarding\") or user journey stage (e.g. \"acquisition\", \"activation\", \"monetization\", \"retention\"). Warning: this REPLACES the property's entire tag list, it does not merge. To keep existing tags, include them alongside the new ones; to remove a tag, omit it. Omit this field entirely to leave tags unchanged.",
"type": "array",
"items": {
"type": "string"
}
},
"property_type": {
"description": "The data type of the property. Controls how the property is parsed, displayed, and filtered.",
"type": "string",
"enum": ["DateTime", "String", "Numeric", "Boolean", "Duration"]
},
"verified": {
"description": "Mark as verified to indicate the property is correctly instrumented and safe to use",
"type": "boolean"
},
"hidden": {
"description": "Mark property as no longer used. Hides it from the UI while preserving historical data",
"type": "boolean"
}
},
"description": "The property definition data to update"
}
},
"required": ["propertyName", "data"]
},
"ReadDataSchemaSchema": {
"type": "object",
"properties": {
"query": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "events"
},
"limit": {
"description": "Number of events to return per page.",
"default": 500,
"type": "integer",
"minimum": 1,
"maximum": 500
},
"offset": {
"description": "Number of events to skip for pagination.",
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": ["kind"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "event_properties"
},
"event_name": {
"type": "string",
"description": "The name of the event that you want to retrieve properties for."
}
},
"required": ["kind", "event_name"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "entity_properties"
},
"entity": {
"type": "string",
"description": "The entity to read: `person`, `session` for the columns of the `sessions` table, or a group type name. The plural form of any of these is accepted too."
}
},
"required": ["kind", "entity"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "action_properties"
},
"action_id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "The ID of the action that you want to retrieve properties for."
}
},
"required": ["kind", "action_id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "entity_property_values"
},
"entity": {
"type": "string",
"description": "The entity to read: `person`, `session` for the columns of the `sessions` table, or a group type name. The plural form of any of these is accepted too."
},
"property_name": {
"type": "string",
"description": "Verified property name of an entity."
}
},
"required": ["kind", "entity", "property_name"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "event_property_values"
},
"event_name": {
"type": "string",
"description": "Verified event name"
},
"property_name": {
"type": "string",
"description": "Verified property name of an event."
}
},
"required": ["kind", "event_name", "property_name"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "action_property_values"
},
"action_id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "Verified action ID"
},
"property_name": {
"type": "string",
"description": "Verified property name of an action."
}
},
"required": ["kind", "action_id", "property_name"],
"additionalProperties": false
}
],
"description": "The data schema query to execute."
}
},
"required": ["query"]
},
"SavedMetricsAttachSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "ID of an existing shared/saved metric. Discover IDs with experiment-saved-metrics-list."
},
"metadata": {
"description": "Optional per-link metadata. Omit to default this metric to primary.",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["primary", "secondary"],
"description": "Whether this metric is a primary or secondary metric on the experiment."
}
},
"required": ["type"]
}
},
"required": ["id"]
},
"description": "The complete desired set of shared (saved) metrics for the experiment — this REPLACES all existing saved-metric links, it does not append. To add or remove one, first read the experiment's current saved_metrics via experiment-get and resend the full set. Pass an empty array to detach all shared metrics."
},
"ScannerEstimateRecordingsFilterSchema": {
"description": "Which recordings to count, as a `RecordingsQuery`. Omit every filter to count every recording. The date range is ignored, because the estimate counts a recent window (`window_days` in the response) and scales it to 30 days.",
"type": "object",
"properties": {
"kind": {
"default": "RecordingsQuery",
"type": "string",
"const": "RecordingsQuery"
},
"events": {
"description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"actions": {
"description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"properties": {
"description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"having_predicates": {
"description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"console_log_filters": {
"description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"operand": {
"description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
"anyOf": [
{
"type": "string",
"enum": ["AND", "OR"]
},
{
"type": "null"
}
]
},
"filter_test_accounts": {
"description": "Leave out recordings from internal and test accounts.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"additionalProperties": {}
},
"ScannerRecordingsFilterSchema": {
"description": "Which recordings the scanner watches, as a `RecordingsQuery`. Omit every filter to watch every new recording. The date range is ignored, because the schedule controls time.",
"type": "object",
"properties": {
"kind": {
"default": "RecordingsQuery",
"type": "string",
"const": "RecordingsQuery"
},
"events": {
"description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"actions": {
"description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"properties": {
"description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"having_predicates": {
"description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"console_log_filters": {
"description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"operand": {
"description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
"anyOf": [
{
"type": "string",
"enum": ["AND", "OR"]
},
{
"type": "null"
}
]
},
"filter_test_accounts": {
"description": "Leave out recordings from internal and test accounts.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"additionalProperties": {}
},
"ScannerUpdateRecordingsFilterSchema": {
"description": "The filter that replaces the scanner's current one, as a `RecordingsQuery`. It is not merged: any field you leave out is cleared, and `{}` watches every new recording. To change part of the filter, read the current one with `vision-scanners-get`, change it, and send it back in full. The date range is ignored, because the schedule controls time.",
"type": "object",
"properties": {
"kind": {
"default": "RecordingsQuery",
"type": "string",
"const": "RecordingsQuery"
},
"events": {
"description": "Events a recording must contain, such as `{\"id\": \"$pageview\", \"type\": \"events\", \"order\": 0}`. Each can carry `properties` that filter that event.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"actions": {
"description": "Saved actions a recording must contain, such as `{\"id\": 12, \"type\": \"actions\", \"order\": 0}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"properties": {
"description": "Recording, session, person and cohort filters, such as `{\"type\": \"recording\", \"key\": \"visited_page\", \"value\": \"/checkout\", \"operator\": \"icontains\"}` or `{\"type\": \"cohort\", \"key\": \"id\", \"value\": 7, \"operator\": \"in\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"having_predicates": {
"description": "Duration filters, such as `{\"type\": \"recording\", \"key\": \"active_seconds\", \"value\": 60, \"operator\": \"gt\"}`. These always apply with AND, whatever `operand` says.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"console_log_filters": {
"description": "Console log filters, such as `{\"type\": \"log_entry\", \"key\": \"level\", \"value\": [\"error\"], \"operator\": \"exact\"}`.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"operand": {
"description": "How `events`, `actions`, `properties` and `console_log_filters` combine. `AND`, the default when omitted, keeps recordings that match every condition. `OR` keeps recordings that match any one. An explicit `null` is read as `OR`. `having_predicates` and `filter_test_accounts` always apply with AND.",
"anyOf": [
{
"type": "string",
"enum": ["AND", "OR"]
},
{
"type": "null"
}
]
},
"filter_test_accounts": {
"description": "Leave out recordings from internal and test accounts.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"additionalProperties": {}
},
"ScoreDefinitionConfigSchema": {
"anyOf": [
{
"type": "object",
"properties": {
"options": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Stable option key — lowercase letters, numbers, underscores, hyphens. Sent back when this option is selected."
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "Human-readable label shown in the review UI."
}
},
"required": ["key", "label"]
},
"description": "Ordered categorical options. Must contain at least one option with unique keys."
},
"selection_mode": {
"description": "Whether reviewers select one option or many. Defaults to \"single\".",
"type": "string",
"enum": ["single", "multiple"]
},
"min_selections": {
"description": "Minimum selections required. Only valid when selection_mode is \"multiple\".",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"max_selections": {
"description": "Maximum selections allowed. Only valid when selection_mode is \"multiple\".",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"passing_rule": {
"description": "Optional passing categories. Omit or set null for neutral scores. Each version keeps its own rule.",
"anyOf": [
{
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"description": "Passing category keys. Every returned category must be included."
}
},
"required": ["categories"],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": ["options"],
"additionalProperties": false,
"description": "Config shape used when kind is \"categorical\"."
},
{
"type": "object",
"properties": {
"min": {
"description": "Optional inclusive minimum score.",
"type": "number"
},
"max": {
"description": "Optional inclusive maximum score (must be ≥ min).",
"type": "number"
},
"step": {
"description": "Optional increment step for numeric input, e.g. 1 or 0.5.",
"type": "number",
"exclusiveMinimum": 0
},
"passing_rule": {
"description": "Optional passing rule. Omit or set null for neutral scores. Each version keeps its own rule.",
"anyOf": [
{
"type": "object",
"properties": {
"operator": {
"type": "string",
"enum": ["gte", "lte"],
"description": "Pass at or above (gte), or at or below (lte), the threshold."
},
"threshold": {
"type": "number",
"description": "Finite passing threshold within any configured score bounds."
}
},
"required": ["operator", "threshold"],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"description": "Config shape used when kind is \"numeric\"."
},
{
"type": "object",
"properties": {
"true_label": {
"description": "Optional label shown for the true branch (e.g. \"Yes\").",
"type": "string",
"minLength": 1
},
"false_label": {
"description": "Optional label shown for the false branch (e.g. \"No\").",
"type": "string",
"minLength": 1
},
"true_is_failure": {
"description": "Whether true means failure. False, omitted, or null means true passes in offline evaluations.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"description": "Config shape used when kind is \"boolean\"."
}
],
"description": "Immutable scorer configuration. Pick the shape matching the scorer kind: categorical (options + selection_mode + optional passing_rule.categories), numeric (min/max/step + optional passing_rule), or boolean (true_label/false_label + optional true_is_failure). The server validates the shape against the kind on the parent scorer and returns 400 on a mismatch."
},
"SignalReportFeedbackNoteSchema": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "The person's context for why the report was or was not useful, up to 4000 characters."
},
"SignalReportFeedbackSentimentSchema": {
"type": "string",
"enum": ["positive", "negative"],
"description": "The report rating: 'positive' (thumbs up) or 'negative' (thumbs down)."
},
"TaskAgentCreateSchema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 255
},
"description": {
"type": "string",
"minLength": 1,
"description": "Instructions for the agent."
},
"repository": {
"description": "Repository in organization/repo format.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"branch": {
"description": "Base branch for the run.",
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 255
},
{
"type": "null"
}
]
},
"scheduled_at": {
"description": "Earliest start time for a one-off run. Use a future ISO 8601 timestamp within 30 days. Times without an offset use UTC. Omit to start immediately.",
"anyOf": [
{
"type": "string",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z||([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"model": {
"description": "Omit to use saved defaults, or the prior model on resume. For an explicit choice, first call tasks-models-retrieve. The server derives the runtime adapter and saves the choice now.",
"type": "string",
"minLength": 1
},
"reasoning_effort": {
"description": "Optional effort supported by the selected model. Requires model. See tasks-models-retrieve.",
"type": "string",
"enum": ["low", "medium", "high", "xhigh", "max", "ultracode"]
}
},
"required": ["description"]
},
"TaskAgentRunCreateSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Task ID."
},
"branch": {
"description": "Git branch to check out in the sandbox.",
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
},
"resume_from_run_id": {
"description": "ID of a previous run to resume from.",
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"pending_user_message": {
"description": "Initial or follow-up message for the run.",
"type": "string"
},
"scheduled_at": {
"description": "Earliest start time for a one-off run. Use a future ISO 8601 timestamp within 30 days. Times without an offset use UTC. Omit to start immediately.",
"anyOf": [
{
"type": "string",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z||([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"model": {
"description": "Omit to use saved defaults, or the prior model on resume. For an explicit choice, first call tasks-models-retrieve. The server derives the runtime adapter and saves the choice now.",
"type": "string",
"minLength": 1
},
"reasoning_effort": {
"description": "Optional effort supported by the selected model. Requires model. See tasks-models-retrieve.",
"type": "string",
"enum": ["low", "medium", "high", "xhigh", "max", "ultracode"]
}
},
"required": ["id"]
},
"UpdateFeatureFlagFiltersSchema": {
"type": "object",
"properties": {
"groups": {
"description": "Release condition groups for the feature flag.",
"type": "array",
"items": {
"type": "object",
"properties": {
"properties": {
"description": "Property conditions for this release condition group.",
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"description": "Property filter type. Set it on every property. Use `group` with `group_type_index` to filter on a group's properties.\n\n* `cohort` - cohort\n* `person` - person\n* `group` - group",
"type": "string",
"enum": ["cohort", "person", "group"]
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"value": {
"description": "Comparison value for the property filter. Supports strings, numbers, booleans, and arrays."
},
"operator": {
"type": "string",
"enum": [
"exact",
"is_not",
"icontains",
"not_icontains",
"starts_with",
"not_starts_with",
"ends_with",
"not_ends_with",
"regex",
"not_regex",
"gt",
"gte",
"lt",
"lte"
],
"description": "Operator used to compare the property value.\n\n* `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* `gte` - gte\n* `lt` - lt\n* `lte` - lte"
}
},
"required": ["key", "value", "operator"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"description": "Property filter type. Set it on every property. Use `group` with `group_type_index` to filter on a group's properties.\n\n* `cohort` - cohort\n* `person` - person\n* `group` - group",
"type": "string",
"enum": ["cohort", "person", "group"]
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": ["is_set", "is_not_set"],
"description": "Existence operator.\n\n* `is_set` - is_set\n* `is_not_set` - is_not_set"
},
"value": {
"description": "Optional value. Runtime behavior determines whether this is ignored."
}
},
"required": ["key", "operator"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"description": "Property filter type. Set it on every property. Use `group` with `group_type_index` to filter on a group's properties.\n\n* `cohort` - cohort\n* `person` - person\n* `group` - group",
"type": "string",
"enum": ["cohort", "person", "group"]
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": ["is_date_exact", "is_date_before", "is_date_after"],
"description": "Date comparison operator.\n\n* `is_date_exact` - is_date_exact\n* `is_date_after` - is_date_after\n* `is_date_before` - is_date_before"
},
"value": {
"type": "string",
"description": "Date value in ISO format or relative date expression."
}
},
"required": ["key", "operator", "value"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"description": "Property filter type. Set it on every property. Use `group` with `group_type_index` to filter on a group's properties.\n\n* `cohort` - cohort\n* `person` - person\n* `group` - group",
"type": "string",
"enum": ["cohort", "person", "group"]
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": [
"semver_eq",
"semver_neq",
"semver_gt",
"semver_gte",
"semver_lt",
"semver_lte",
"semver_tilde",
"semver_caret",
"semver_wildcard"
],
"description": "Semantic version comparison operator.\n\n* `semver_eq` - semver_eq\n* `semver_neq` - semver_neq\n* `semver_gt` - semver_gt\n* `semver_gte` - semver_gte\n* `semver_lt` - semver_lt\n* `semver_lte` - semver_lte\n* `semver_tilde` - semver_tilde\n* `semver_caret` - semver_caret\n* `semver_wildcard` - semver_wildcard"
},
"value": {
"type": "string",
"description": "Semantic version string."
}
},
"required": ["key", "operator", "value"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"description": "Property filter type. Set it on every property. Use `group` with `group_type_index` to filter on a group's properties.\n\n* `cohort` - cohort\n* `person` - person\n* `group` - group",
"type": "string",
"enum": ["cohort", "person", "group"]
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": ["icontains_multi", "not_icontains_multi"],
"description": "Multi-contains operator.\n\n* `icontains_multi` - icontains_multi\n* `not_icontains_multi` - not_icontains_multi"
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of strings to evaluate against."
}
},
"required": ["key", "operator", "value"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"type": "string",
"enum": ["cohort"],
"description": "Cohort property type required for in/not_in operators.\n\n* `cohort` - cohort"
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": ["in", "not_in"],
"description": "Membership operator for cohort properties.\n\n* `in` - in\n* `not_in` - not_in"
},
"value": {
"description": "Cohort comparison value (single or list, depending on usage)."
},
"cohort_deleted": {
"description": "Set to true in responses when the cohort is deleted or does not exist. The flag cannot evaluate this condition. Ignored on write.",
"type": "boolean"
},
"cohort_missing": {
"description": "Set to true in responses when no cohort with this id exists in the project, so it cannot be restored. `cohort_deleted` is also true. Absent for a soft-deleted cohort. Ignored on write.",
"type": "boolean"
}
},
"required": ["key", "type", "operator", "value"]
},
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key used in this feature flag condition."
},
"type": {
"type": "string",
"enum": ["flag"],
"description": "Flag property type required for flag dependency checks.\n\n* `flag` - flag"
},
"cohort_name": {
"description": "Resolved cohort name for cohort-type filters.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group_type_index": {
"description": "Group type index a `group` filter reads properties from. Defaults to the condition set's `aggregation_group_type_index`.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"operator": {
"type": "string",
"enum": ["flag_evaluates_to"],
"description": "Operator for feature flag dependency evaluation.\n\n* `flag_evaluates_to` - flag_evaluates_to"
},
"value": {
"description": "Value to compare flag evaluation against."
}
},
"required": ["key", "type", "operator", "value"]
}
]
}
},
"rollout_percentage": {
"description": "Rollout percentage for this release condition group.",
"type": "number"
},
"variant": {
"description": "Variant key override for multivariate flags.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"aggregation_group_type_index": {
"description": "Group type index for this condition set. None means person-level aggregation.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"condition_id": {
"description": "The condition_id this condition had when you read the flag. Send it unchanged when you keep, edit, or move the condition. Leave it off a new condition or one copied from a different flag. The update is refused when no condition on the flag has this ID.",
"type": "string"
}
}
}
},
"multivariate": {
"description": "Multivariate configuration for variant-based rollouts.",
"anyOf": [
{
"type": "object",
"properties": {
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Unique key for this variant."
},
"name": {
"description": "Human-readable name for this variant.",
"type": "string"
},
"rollout_percentage": {
"type": "number",
"description": "Variant rollout percentage."
}
},
"required": ["key", "rollout_percentage"]
},
"description": "Variant definitions for multivariate feature flags."
}
},
"required": ["variants"]
},
{
"type": "null"
}
]
},
"aggregation_group_type_index": {
"description": "Group type index for group-based feature flags.",
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payloads": {
"description": "Optional payload values keyed by variant key.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"feature_enrollment": {
"description": "Whether this flag has early access feature enrollment enabled. When true, the flag is evaluated against the person property $feature_enrollment/{flag_key}.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"early_exit": {
"default": false,
"description": "When true, condition evaluation stops at the first matching condition set rather than continuing to evaluate subsequent groups.",
"type": "boolean"
}
},
"description": "Full release-condition object. It replaces the stored filters, so read the flag first and send every condition you want to keep. The tool description covers condition_id and group targeting."
},
"UsageMetricFiltersSchema": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"const": "data_warehouse"
},
"table_name": {
"type": "string",
"description": "Name of a synced data warehouse table. Use `external-data-schemas-list` to discover available tables."
},
"timestamp_field": {
"type": "string",
"description": "Timestamp column or HogQL expression on the row (e.g. \"created\" or \"toDateTime(created_at)\"). Use `execute-sql` (`SELECT * FROM <table> LIMIT 1`) to inspect available columns."
},
"key_field": {
"type": "string",
"description": "Column on the row whose value matches the entity key. v1 supports group profiles only — the column value is compared to the group_key."
}
},
"required": ["source", "table_name", "timestamp_field", "key_field"],
"description": "Data-warehouse-source filter shape."
},
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Event name (e.g. \"$pageview\")."
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"const": "events"
},
"order": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"properties": {
"type": "array",
"items": {}
}
},
"required": ["id"]
},
"description": "Events to count or sum over."
},
"actions": {
"type": "array",
"items": {}
},
"properties": {
"type": "array",
"items": {}
},
"filter_test_accounts": {
"type": "boolean"
}
},
"required": ["events"],
"description": "Events-source filter shape (default)."
}
],
"description": "Filter definition. Pick exactly one branch: `data_warehouse` (set `source: \"data_warehouse\"` plus `table_name`/`timestamp_field`/`key_field`) or `events` (HogFunction filter shape with an `events` array)."
},
"WikiPageReadLimitSchema": {
"default": 12000,
"type": "integer",
"minimum": 1,
"maximum": 12000
},
"WorkflowActionEmailPatchSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The workflow (HogFlow) id."
},
"action_id": {
"type": "string",
"description": "Id of the function_email step whose email to edit."
},
"operations": {
"description": "Ordered edits applied atomically to the step's email design - the same operations as workflows-patch-email-template. The result is re-rendered to HTML server-side, so the sent email always matches the patched design. Reference blocks by id (read them via workflows-get).",
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_content"
},
"id": {
"type": "string",
"description": "Id of the content block to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial content-block fields, deep-merged into the existing block; a null leaf deletes that key. e.g. {values: {text: '<p>Hi</p>'}} changes only the block's text."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_column"
},
"id": {
"type": "string",
"description": "Id of the column to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial column fields, deep-merged; a null leaf deletes that key."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_row"
},
"id": {
"type": "string",
"description": "Id of the row to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial row fields, deep-merged; a null leaf deletes that key."
}
},
"required": ["op", "id", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_body"
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial body fields, deep-merged. e.g. {values: {backgroundColor: '#ffffff'}}."
}
},
"required": ["op", "patch"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_content"
},
"column_id": {
"type": "string",
"description": "Id of the column to insert the block into."
},
"content": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "A content block {type, values: {...}}; omit id and values._meta — they are assigned server-side. type is one of text, heading, button, image, divider, html, etc."
},
"index": {
"description": "0-based insert position; omit to append to the end.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "column_id", "content"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_content"
},
"id": {
"type": "string",
"description": "Id of the content block to remove."
}
},
"required": ["op", "id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "move_content"
},
"id": {
"type": "string",
"description": "Id of the content block to move."
},
"column_id": {
"type": "string",
"description": "Id of the destination column."
},
"index": {
"description": "0-based position in the destination column; omit to append.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "id", "column_id"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_row"
},
"row": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "A full row {cells, columns: [{contents: [...], values}], values}; ids and Unlayer numbering are assigned server-side for the row and everything nested in it."
},
"index": {
"description": "0-based insert position; omit to append to the end.",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["op", "row"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_row"
},
"id": {
"type": "string",
"description": "Id of the row to remove."
}
},
"required": ["op", "id"],
"additionalProperties": false
}
]
}
},
"email_patch": {
"description": "Partial email fields deep-merged into the step's email (a null leaf deletes the key): subject, preheader, text, to, from, replyTo, cc, bcc. The design is edited via operations, and html is always re-rendered from it.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"base_updated_at": {
"description": "Optimistic concurrency: the updated_at (or draft_updated_at) last loaded. If the stored workflow is newer, the patch is rejected with 409 instead of clobbering a concurrent edit.",
"type": "string"
}
},
"required": ["id", "action_id"]
},
"WorkflowGraphPatchSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The workflow (HogFlow) id to edit."
},
"operations": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "update_action"
},
"id": {
"type": "string",
"description": "Id of the action to update."
},
"patch": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Partial action fields, deep-merged into the existing action; a null leaf deletes that key. e.g. {config: {inputs: {subject: {value: \"Hi\"}}}} changes only that one input."
}
},
"required": ["op", "id", "patch"]
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_action"
},
"action": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "A full action node {id, name, type, config, ...}; same shape as entries in the workflow actions array."
}
},
"required": ["op", "action"]
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_action"
},
"id": {
"type": "string",
"description": "Id of the action to remove. Its incoming edges reconnect to its first outgoer."
}
},
"required": ["op", "id"]
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "add_edge"
},
"edge": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Source action id."
},
"to": {
"type": "string",
"description": "Target action id."
},
"type": {
"type": "string",
"enum": ["continue", "branch"],
"description": "'continue' = fall-through (sequential or no-match path); 'branch' = a condition/cohort branch (needs index)."
},
"index": {
"description": "Required for type=branch: which condition/cohort slot this branch matches (0-based).",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["from", "to", "type"],
"description": "The edge to add."
}
},
"required": ["op", "edge"]
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "remove_edge"
},
"edge": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Source action id."
},
"to": {
"type": "string",
"description": "Target action id."
},
"type": {
"type": "string",
"enum": ["continue", "branch"],
"description": "'continue' = fall-through (sequential or no-match path); 'branch' = a condition/cohort branch (needs index)."
},
"index": {
"description": "Required for type=branch: which condition/cohort slot this branch matches (0-based).",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["from", "to", "type"],
"description": "The edge to remove (matched on from/to/type/index)."
}
},
"required": ["op", "edge"]
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"const": "replace_action_edges"
},
"id": {
"type": "string",
"description": "Action id whose outgoing edges are being replaced."
},
"edges": {
"type": "array",
"items": {
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Source action id."
},
"to": {
"type": "string",
"description": "Target action id."
},
"type": {
"type": "string",
"enum": ["continue", "branch"],
"description": "'continue' = fall-through (sequential or no-match path); 'branch' = a condition/cohort branch (needs index)."
},
"index": {
"description": "Required for type=branch: which condition/cohort slot this branch matches (0-based).",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": ["from", "to", "type"]
},
"description": "The complete set of the action's outgoing edges; incoming edges are preserved."
}
},
"required": ["op", "id", "edges"]
}
]
},
"description": "Ordered graph edits applied atomically: the stored graph is read, ops are applied in order, the result is fully validated, and it is saved only if valid — otherwise the workflow is left unchanged. Reference nodes/edges by id so you never resend the whole graph. The full updated workflow is returned."
}
},
"required": ["id", "operations"]
}
}
}