: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
/**
* Auto-generated from the Django backend OpenAPI schema.
* MCP service uses these Zod schemas for generated tool handlers.
* To regenerate: hogli build:openapi
*
* PostHog API - MCP 21 enabled ops
* OpenAPI spec version: 1.0.0
*/
import * as zod from 'zod'
/**
* Canvases: agent-built sandboxed browser apps, filed into channels.
*
* Source is versioned per publish and built server-side; the canvas app
* renders the published build's artifact from the isolated artifact origin.
*/
export const CanvasesListParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesListQueryLimitMax = 1000
export const CanvasesListQueryParams = () => zod.object({
channel: zod.string().optional().describe('Only return canvases in this channel.'),
created_by: zod.string().optional().describe('Only return canvases created by the user with this UUID.'),
kind: zod
.enum(['component', 'freeform', 'grid'])
.optional()
.describe('Only return canvases of this kind. kind=component lists the component store.'),
limit: zod.number().max(canvasesListQueryLimitMax).optional().describe('Number of results to return per page.'),
offset: zod.number().optional().describe('The initial index from which to return the results.'),
ordering: zod
.enum(['-created_at', '-updated_at'])
.optional()
.describe(
'Sort order. -created_at (default) puts the newest canvases first. -updated_at puts the most recently changed canvases first.'
),
search: zod
.string()
.optional()
.describe('Only return canvases whose name or description contains this text (case-insensitive).'),
})
/**
* Create a new, empty canvas in a channel; give it source by publishing a project.
*/
export const CanvasesCreateParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesCreateBodyNameMax = 400
export const canvasesCreateBodyKindDefault = `freeform`
export const canvasesCreateBodyDescriptionDefault = ``
export const canvasesCreateBodyTemplateIdDefault = `freeform`
export const canvasesCreateBodyTemplateIdMax = 64
export const CanvasesCreateBody = () => zod
.object({
name: zod.string().max(canvasesCreateBodyNameMax).describe('Display name for the canvas.'),
channel_id: zod.string().describe('Id of the channel the canvas belongs to.'),
kind: zod
.enum(['freeform', 'grid', 'component'])
.describe('\* `freeform` - freeform\n\* `grid` - grid\n\* `component` - component')
.default(canvasesCreateBodyKindDefault)
.describe(
"What to create: 'freeform' (a standalone app), 'component' (a reusable widget for grids — its published project must declare a `component` placement contract), or 'grid' (a composition of components, edited through the layout endpoints).\n\n\* `freeform` - freeform\n\* `grid` - grid\n\* `component` - component"
),
description: zod
.string()
.default(canvasesCreateBodyDescriptionDefault)
.describe(
'Short prose describing the canvas. For components this is the store-search text agents match against — say what the widget shows and what its config controls.'
),
template_id: zod
.string()
.max(canvasesCreateBodyTemplateIdMax)
.default(canvasesCreateBodyTemplateIdDefault)
.describe('Canvas template identifier.'),
})
.describe('Payload for creating a new, empty canvas in a channel.')
/**
* Update canvas metadata, including the space it belongs to.
*/
export const CanvasesPartialUpdateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesPartialUpdateBodyNameMax = 400
export const CanvasesPartialUpdateBody = () => zod
.object({
name: zod.string().max(canvasesPartialUpdateBodyNameMax).optional().describe('Updated display name.'),
description: zod
.string()
.optional()
.describe('Updated canvas description (for components, the store-search text).'),
channel_id: zod.string().optional().describe('Id of the space the canvas belongs to.'),
pinned: zod.boolean().optional().describe('Whether the canvas is pinned in its channel.'),
generation_task_id: zod
.string()
.nullish()
.describe('Task currently generating this canvas, or null to clear it.'),
})
.describe('Writable canvas fields: metadata only — source changes go through publish\/edit.')
/**
* Read the canvas's build lifecycle: live pointers plus recent builds.
*
* A publish queues a build; poll this until it is ready (the live pointer
* advances) or failed (fix the error diagnostics and publish again — the
* last good build stays live). Send the response's ETag back as
* If-None-Match to make the poll revalidate without a body.
*/
export const CanvasesBuildsRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesBuildsRetrieveQueryParams = () => zod.object({
scope: zod
.string()
.optional()
.describe(
'\"slim\" returns only what rendering needs — the live build, the head version\'s builds, and anything still in flight — instead of the full recent-build history. Any other value (or none) returns the full window.'
),
version_id: zod
.string()
.optional()
.describe('Include the retained ready build for this historical source version.'),
})
/**
* The comment threads on this canvas, newest first. Open threads only unless include_resolved is set.
*/
export const CanvasesCommentsListParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesCommentsListQueryCursorMax = 256
export const canvasesCommentsListQueryIncludeResolvedDefault = false
export const canvasesCommentsListQueryLimitDefault = 50
export const canvasesCommentsListQueryLimitMax = 100
export const CanvasesCommentsListQueryParams = () => zod.object({
cursor: zod
.string()
.min(1)
.max(canvasesCommentsListQueryCursorMax)
.optional()
.describe('Opaque cursor returned by the previous page.'),
include_resolved: zod
.boolean()
.default(canvasesCommentsListQueryIncludeResolvedDefault)
.describe('Whether to include resolved comment threads.'),
limit: zod
.number()
.min(1)
.max(canvasesCommentsListQueryLimitMax)
.default(canvasesCommentsListQueryLimitDefault)
.describe('Maximum number of root comments to return.'),
})
/**
* One comment thread on this canvas: the root comment and its replies, oldest first.
*/
export const CanvasesCommentsRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
root_comment_id: zod.string(),
})
export const canvasesCommentsRetrieveQueryContentOffsetDefault = 0
export const canvasesCommentsRetrieveQueryContentOffsetMin = 0
export const canvasesCommentsRetrieveQueryCursorMax = 256
export const canvasesCommentsRetrieveQueryLimitDefault = 50
export const canvasesCommentsRetrieveQueryLimitMax = 100
export const CanvasesCommentsRetrieveQueryParams = () => zod.object({
comment_id: zod
.string()
.optional()
.describe('Comment id whose truncated body should continue. Use with content_offset.'),
content_offset: zod
.number()
.min(canvasesCommentsRetrieveQueryContentOffsetMin)
.default(canvasesCommentsRetrieveQueryContentOffsetDefault)
.describe('Byte offset returned as content_next_offset for the selected comment.'),
cursor: zod
.string()
.min(1)
.max(canvasesCommentsRetrieveQueryCursorMax)
.optional()
.describe('Opaque cursor returned by the previous page.'),
limit: zod
.number()
.min(1)
.max(canvasesCommentsRetrieveQueryLimitMax)
.default(canvasesCommentsRetrieveQueryLimitDefault)
.describe('Maximum number of comments in the thread to return.'),
})
/**
* Stage a complete source project as a draft version and build it, without publishing.
*
* The draft gets the same validation, versioning, and server-side build as
* a publish, but the canvas's head and live build never move, so nothing
* changes for viewers. Promote the version with `promote` to make it live.
* The response reports how the draft's declared capabilities widen the
* current head's, so growth in access can be reviewed before it ships.
* No version guard applies: a draft conflicts with nothing.
*/
export const CanvasesDraftCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesDraftCreateBodyProjectOneAssetsContentMax = 2796204
export const canvasesDraftCreateBodyProjectOneAssetsContentRegExp = new RegExp(
'^(?:[A-Za-z0-9+\/]{4})\*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$'
)
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneDefaultWMax = 12
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneDefaultHMax = 40
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneMinWMax = 12
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneMinHMax = 40
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneMaxWMax = 12
export const canvasesDraftCreateBodyProjectOneComponentOneSizeOneMaxHMax = 40
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax = 128
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax = 100
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax = 200
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax = 100
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogStateMax = 2
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax = 64
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogActionsMax = 32
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax = 200
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogToolsMax = 32
export const canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault = false
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax = 2048
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax = 20
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax = 300
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax = 200
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax = 64
export const canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsMax = 20
export const CanvasesDraftCreateBody = () => zod
.object({
project: zod
.object({
schemaVersion: zod.number().describe('Source-project schema version. Currently always 1.'),
files: zod
.record(zod.string(), zod.string())
.describe("Project files keyed by relative path (forward slashes, no '..')."),
assets: zod
.record(
zod.string(),
zod.object({
encoding: zod.enum(['base64']).describe('\* `base64` - base64'),
contentType: zod
.enum([
'image/png',
'image/jpeg',
'image/gif',
'image/webp',
'image/svg+xml',
'font/woff',
'font/woff2',
'application/wasm',
'application/octet-stream',
])
.describe(
'\* `image\/png` - image\/png\n\* `image\/jpeg` - image\/jpeg\n\* `image\/gif` - image\/gif\n\* `image\/webp` - image\/webp\n\* `image\/svg+xml` - image\/svg+xml\n\* `font\/woff` - font\/woff\n\* `font\/woff2` - font\/woff2\n\* `application\/wasm` - application\/wasm\n\* `application\/octet-stream` - application\/octet-stream'
),
content: zod
.string()
.max(canvasesDraftCreateBodyProjectOneAssetsContentMax)
.regex(canvasesDraftCreateBodyProjectOneAssetsContentRegExp),
})
)
.optional()
.describe('Optional base64-encoded binary assets keyed by safe project-relative paths.'),
entryHtml: zod.string().describe('The project\'s entry HTML file. Currently always \"index.html\".'),
dependencies: zod
.record(zod.string(), zod.string())
.optional()
.describe(
'Exact-version dependencies, restricted to the platform-supported set at its pinned versions.'
),
canvasSdkVersion: zod
.string()
.optional()
.describe('Version of the host-injected `ph` canvas SDK the project targets.'),
component: zod
.object({
size: zod
.object({
defaultW: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneDefaultWMax)
.describe('Width a new placement starts at, in grid columns.'),
defaultH: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneDefaultHMax)
.describe('Height a new placement starts at, in grid rows.'),
minW: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneMinWMax)
.describe('Narrowest width the component renders usefully at.'),
minH: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneMinHMax)
.describe('Shortest height the component renders usefully at.'),
maxW: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneMaxWMax)
.optional()
.describe("Widest allowed width; omit for no cap below the grid's width."),
maxH: zod
.number()
.min(1)
.max(canvasesDraftCreateBodyProjectOneComponentOneSizeOneMaxHMax)
.optional()
.describe('Tallest allowed height; omit for no cap.'),
})
.describe("A component's grid-size contract, in grid units.")
.describe('Grid-size contract for placements of this component.'),
configSchema: zod
.record(zod.string(), zod.unknown())
.optional()
.describe(
'JSON Schema (\"type\": \"object\") for a placement\'s config. The host validates each placement\'s config against it and passes the validated object to the widget at mount.'
),
})
.describe("A component's placement contract: how grid canvases may place and configure it.")
.optional()
.describe(
'Placement contract, required for (and only allowed on) component-kind canvases: the grid size the component takes and the JSON Schema of its per-placement config.'
),
capabilities: zod
.object({
posthog: zod.object({
insights: zod
.array(
zod
.string()
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax),
inlineQueries: zod.boolean(),
captureEvents: zod
.array(
zod
.string()
.max(
canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax
)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax),
state: zod
.array(zod.enum(['user', 'shared']).describe('\* `user` - user\n\* `shared` - shared'))
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogStateMax)
.optional()
.describe(
"State scopes the canvas may use via ph.state: 'user' (private to each viewer) and\/or 'shared' (one value per canvas, team-visible)."
),
actions: zod
.array(
zod
.string()
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogActionsMax)
.optional()
.describe(
"Registered action verbs the canvas may invoke via ph.actions (e.g. 'annotations.create', 'tasks.create'). Each executes as the viewer; declaring one shows it in the promote review."
),
tools: zod
.array(
zod
.string()
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogToolsMax)
.optional()
.describe(
"PostHog MCP tools the canvas may run via ph.tools (e.g. 'feature-flag-get-definition', 'feature-flag-set-release-condition-rollout'). Each runs as the viewer; declaring one shows it in the promote review."
),
agentRequests: zod
.boolean()
.default(canvasesDraftCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault),
}),
network: zod.object({
origins: zod
.array(
zod.url().max(canvasesDraftCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax),
}),
connectors: zod
.array(
zod
.object({
provider: zod
.string()
.max(
canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax
)
.describe(
"Connector provider id: a native provider such as 'github', or 'mcp:<server host>' (e.g. 'mcp:mcp.calendly.com') for a server the viewer connected in the MCP store."
),
tools: zod
.array(
zod
.string()
.max(
canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax
)
)
.min(1)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax)
.describe(
'Tool names the canvas may call on this provider. Read-only tools only.'
),
})
.describe(
'One provider a canvas may call through ph.connectors, with the tools it may use.'
)
)
.max(canvasesDraftCreateBodyProjectOneCapabilitiesOneConnectorsMax)
.optional()
.describe(
"Third-party providers the canvas reads through ph.connectors, each with the tools it may call. Every call runs with the viewer's own connection; declaring one shows it in the promote review."
),
})
.optional()
.describe(
'Bounded capabilities frozen into the built artifact. Declare every insight short id the canvas loads, every event it captures, and inlineQueries when it runs ad-hoc HogQL — the host enforces these at runtime and validation rejects undeclared `ph` calls. Network origins must be exact HTTPS origins. Data fetched by canvas code can be sent to those origins.'
),
})
.describe("A canvas's multi-file source project — the canonical write format for canvas source.")
.describe('The complete source project to stage as a draft.'),
prompt: zod
.string()
.optional()
.describe("Short description of the change, stored on the draft's version history entry."),
})
.describe('Payload for staging a complete source project as a draft build.')
/**
* The canvas's staged draft versions, newest first, each with its latest build status.
*
* A draft is a version that was built but never made the head. Preview one
* with `source?version_id=`, then make it live with `promote`.
*/
export const CanvasesDraftsRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
/**
* Publish file edits against the canvas's current source project.
*
* Diff-aware alternative to sending the complete project: operations
* replace text inside a file, write, delete, or rename files, applied in
* order to the head the caller read. `expected_current_version_id` is mandatory here —
* relative edits against an unverified base could silently merge into
* someone else's newer work.
*/
export const CanvasesEditCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesEditCreateBodyOperationsItemReplaceAllDefault = false
export const canvasesEditCreateBodyCapabilitiesOnePosthogInsightsItemMax = 128
export const canvasesEditCreateBodyCapabilitiesOnePosthogInsightsMax = 100
export const canvasesEditCreateBodyCapabilitiesOnePosthogCaptureEventsItemMax = 200
export const canvasesEditCreateBodyCapabilitiesOnePosthogCaptureEventsMax = 100
export const canvasesEditCreateBodyCapabilitiesOnePosthogStateMax = 2
export const canvasesEditCreateBodyCapabilitiesOnePosthogActionsItemMax = 64
export const canvasesEditCreateBodyCapabilitiesOnePosthogActionsMax = 32
export const canvasesEditCreateBodyCapabilitiesOnePosthogToolsItemMax = 200
export const canvasesEditCreateBodyCapabilitiesOnePosthogToolsMax = 32
export const canvasesEditCreateBodyCapabilitiesOnePosthogAgentRequestsDefault = false
export const canvasesEditCreateBodyCapabilitiesOneNetworkOriginsItemMax = 2048
export const canvasesEditCreateBodyCapabilitiesOneNetworkOriginsMax = 20
export const canvasesEditCreateBodyCapabilitiesOneConnectorsItemProviderMax = 300
export const canvasesEditCreateBodyCapabilitiesOneConnectorsItemToolsItemMax = 200
export const canvasesEditCreateBodyCapabilitiesOneConnectorsItemToolsMax = 64
export const canvasesEditCreateBodyCapabilitiesOneConnectorsMax = 20
export const canvasesEditCreateBodyNameMax = 400
export const CanvasesEditCreateBody = () => zod
.object({
operations: zod
.array(
zod
.object({
op: zod
.enum(['write', 'delete', 'rename', 'str_replace'])
.describe(
'\* `write` - Write\n\* `delete` - Delete\n\* `rename` - Rename\n\* `str_replace` - Str Replace'
)
.optional()
.describe(
"What to do. 'str_replace' replaces old_string with new_string inside the file: the default for changing an existing file. 'write' sets the file's complete content (new files, full rewrites). 'delete' removes the file. 'rename' moves it to new_path. When omitted, it follows the fields sent: old_string or new_string means 'str_replace', new_path means 'rename', non-null content means 'write', and content null means 'delete'. An operation with none of these fields is rejected.\n\n\* `write` - Write\n\* `delete` - Delete\n\* `rename` - Rename\n\* `str_replace` - Str Replace"
),
path: zod
.string()
.describe('Project-relative path of the file to edit (e.g. \"src\/canvas.tsx\").'),
content: zod.string().nullish().describe("For 'write': the file's complete new content."),
old_string: zod
.string()
.optional()
.describe(
"For 'str_replace': the exact text to replace, copied from the file with a few surrounding lines so it matches one place only. If whitespace differs slightly, a unique line-by-line match is still accepted."
),
new_string: zod
.string()
.optional()
.describe(
"For 'str_replace': the text that replaces old_string. An empty string deletes old_string."
),
replace_all: zod
.boolean()
.default(canvasesEditCreateBodyOperationsItemReplaceAllDefault)
.describe(
"For 'str_replace': replace every exact match of old_string instead of requiring exactly one."
),
new_path: zod
.string()
.optional()
.describe("For 'rename': the file's new project-relative path."),
})
.describe('One file edit: replace text in a file, write a whole file, delete it, or rename it.')
)
.optional()
.describe(
"Edits applied in order to the canvas's current source project, all or nothing. May be empty when the edit only changes capabilities."
),
capabilities: zod
.object({
posthog: zod.object({
insights: zod
.array(zod.string().max(canvasesEditCreateBodyCapabilitiesOnePosthogInsightsItemMax))
.max(canvasesEditCreateBodyCapabilitiesOnePosthogInsightsMax),
inlineQueries: zod.boolean(),
captureEvents: zod
.array(zod.string().max(canvasesEditCreateBodyCapabilitiesOnePosthogCaptureEventsItemMax))
.max(canvasesEditCreateBodyCapabilitiesOnePosthogCaptureEventsMax),
state: zod
.array(zod.enum(['user', 'shared']).describe('\* `user` - user\n\* `shared` - shared'))
.max(canvasesEditCreateBodyCapabilitiesOnePosthogStateMax)
.optional()
.describe(
"State scopes the canvas may use via ph.state: 'user' (private to each viewer) and\/or 'shared' (one value per canvas, team-visible)."
),
actions: zod
.array(zod.string().max(canvasesEditCreateBodyCapabilitiesOnePosthogActionsItemMax))
.max(canvasesEditCreateBodyCapabilitiesOnePosthogActionsMax)
.optional()
.describe(
"Registered action verbs the canvas may invoke via ph.actions (e.g. 'annotations.create', 'tasks.create'). Each executes as the viewer; declaring one shows it in the promote review."
),
tools: zod
.array(zod.string().max(canvasesEditCreateBodyCapabilitiesOnePosthogToolsItemMax))
.max(canvasesEditCreateBodyCapabilitiesOnePosthogToolsMax)
.optional()
.describe(
"PostHog MCP tools the canvas may run via ph.tools (e.g. 'feature-flag-get-definition', 'feature-flag-set-release-condition-rollout'). Each runs as the viewer; declaring one shows it in the promote review."
),
agentRequests: zod
.boolean()
.default(canvasesEditCreateBodyCapabilitiesOnePosthogAgentRequestsDefault),
}),
network: zod.object({
origins: zod
.array(zod.url().max(canvasesEditCreateBodyCapabilitiesOneNetworkOriginsItemMax))
.max(canvasesEditCreateBodyCapabilitiesOneNetworkOriginsMax),
}),
connectors: zod
.array(
zod
.object({
provider: zod
.string()
.max(canvasesEditCreateBodyCapabilitiesOneConnectorsItemProviderMax)
.describe(
"Connector provider id: a native provider such as 'github', or 'mcp:<server host>' (e.g. 'mcp:mcp.calendly.com') for a server the viewer connected in the MCP store."
),
tools: zod
.array(
zod
.string()
.max(canvasesEditCreateBodyCapabilitiesOneConnectorsItemToolsItemMax)
)
.min(1)
.max(canvasesEditCreateBodyCapabilitiesOneConnectorsItemToolsMax)
.describe('Tool names the canvas may call on this provider. Read-only tools only.'),
})
.describe(
'One provider a canvas may call through ph.connectors, with the tools it may use.'
)
)
.max(canvasesEditCreateBodyCapabilitiesOneConnectorsMax)
.optional()
.describe(
"Third-party providers the canvas reads through ph.connectors, each with the tools it may call. Every call runs with the viewer's own connection; declaring one shows it in the promote review."
),
})
.optional()
.describe(
"The project's complete new capabilities, replacing the current ones in the same publish. Send it when the change needs a capability the canvas does not declare yet, for example a new ph.state scope, insight, capture event, or network origin. Copy the current capabilities from canvas-source-retrieve and change only what you need. Omit to keep the current capabilities."
),
prompt: zod
.string()
.optional()
.describe('Short description of the change, stored on the appended version history entry.'),
name: zod
.string()
.max(canvasesEditCreateBodyNameMax)
.optional()
.describe('Optional new display name for the canvas.'),
expected_current_version_id: zod
.string()
.nullable()
.describe(
'Required optimistic-concurrency guard: the current_version_id the edits are based on (null when the canvas has never been published). Diff edits against a moved head are rejected with 409 version_conflict — they cannot be published unguarded.'
),
})
.describe("Payload for publishing per-file edits against the canvas's current source.")
/**
* Read a grid canvas's layout document and its `current_version_id`.
*
* Always call this before editing: pass the returned version id as
* `expected_current_version_id` on publish/patch so concurrent edits are
* not overwritten. A grid canvas with no versions yet returns the
* default empty layout with a null version id.
*/
export const CanvasesLayoutRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesLayoutRetrieveQueryParams = () => zod.object({
include_components: zod
.boolean()
.optional()
.describe(
"Also return the renderable build (with signed artifact URL) of every component the layout's live placements reference, so a grid renders from this one call."
),
version_id: zod
.string()
.optional()
.describe('Read this historical layout version instead of the head (for version browsing).'),
})
/**
* Apply surgical operations to the grid canvas's current layout.
*
* The default write path for both the editor and agents: add, move,
* resize, fill, or remove one placement without resending the layout.
* `expected_current_version_id` is mandatory so an agent filling a box
* and a user rearranging widgets cannot overwrite each other.
*/
export const CanvasesLayoutPatchCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesLayoutPatchCreateBodyOperationsItemGridOneRowHeightMin = 24
export const canvasesLayoutPatchCreateBodyOperationsItemGridOneRowHeightMax = 400
export const canvasesLayoutPatchCreateBodyOperationsItemGridOneGapMin = 0
export const canvasesLayoutPatchCreateBodyOperationsItemGridOneGapMax = 48
export const canvasesLayoutPatchCreateBodyOperationsItemPlacementOneIdMax = 64
export const canvasesLayoutPatchCreateBodyOperationsItemPlacementOneIdRegExp = new RegExp('^[A-Za-z0-9_-]{1,64}$')
export const canvasesLayoutPatchCreateBodyOperationsItemPlacementOneXMin = 0
export const canvasesLayoutPatchCreateBodyOperationsItemPlacementOneYMin = 0
export const canvasesLayoutPatchCreateBodyOperationsItemPlacementOnePromptMax = 10000
export const canvasesLayoutPatchCreateBodyOperationsItemIdMax = 64
export const canvasesLayoutPatchCreateBodyOperationsItemChangesOneXMin = 0
export const canvasesLayoutPatchCreateBodyOperationsItemChangesOneYMin = 0
export const canvasesLayoutPatchCreateBodyOperationsItemChangesOnePromptMax = 10000
export const CanvasesLayoutPatchCreateBody = () => zod
.object({
operations: zod
.array(
zod
.object({
op: zod
.enum(['set_grid', 'add_placement', 'update_placement', 'remove_placement'])
.describe(
'\* `set_grid` - set_grid\n\* `add_placement` - add_placement\n\* `update_placement` - update_placement\n\* `remove_placement` - remove_placement'
)
.describe(
'The operation to apply.\n\n\* `set_grid` - set_grid\n\* `add_placement` - add_placement\n\* `update_placement` - update_placement\n\* `remove_placement` - remove_placement'
),
grid: zod
.object({
columns: zod
.union([
zod.literal(4),
zod.literal(6),
zod.literal(8),
zod.literal(10),
zod.literal(12),
])
.describe('\* `4` - 4\n\* `6` - 6\n\* `8` - 8\n\* `10` - 10\n\* `12` - 12')
.describe(
'Grid width in columns. One of 4, 6, 8, 10, or 12.\n\n\* `4` - 4\n\* `6` - 6\n\* `8` - 8\n\* `10` - 10\n\* `12` - 12'
),
rowHeight: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemGridOneRowHeightMin)
.max(canvasesLayoutPatchCreateBodyOperationsItemGridOneRowHeightMax)
.describe('Height of one grid row, in pixels.'),
gap: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemGridOneGapMin)
.max(canvasesLayoutPatchCreateBodyOperationsItemGridOneGapMax)
.describe('Gap between placements, in pixels.'),
})
.describe('The grid a grid canvas lays its placements out on.')
.optional()
.describe('For set_grid: the new grid definition.'),
placement: zod
.object({
id: zod
.string()
.max(canvasesLayoutPatchCreateBodyOperationsItemPlacementOneIdMax)
.regex(canvasesLayoutPatchCreateBodyOperationsItemPlacementOneIdRegExp)
.describe(
"Stable placement id, unique within the layout. 1-64 characters of letters, digits, '_', or '-'."
),
status: zod
.enum(['pending', 'generating', 'live', 'failed'])
.describe(
'\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed'
)
.describe(
"Placement lifecycle: 'pending' (box drawn, no prompt yet), 'generating' (an agent task is filling it), 'live' (renders its component), 'failed' (generation failed; re-prompt or remove).\n\n\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed"
),
component: zod
.string()
.nullish()
.describe(
'Id of the component canvas this placement renders. Required once the placement is live.'
),
version: zod
.string()
.nullish()
.describe(
'Component version to render: \"latest\" (the default — follows the component\'s published build) or a pinned source version id.'
),
x: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemPlacementOneXMin)
.describe('Left edge, in grid columns (0-based).'),
y: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemPlacementOneYMin)
.describe('Top edge, in grid rows (0-based).'),
w: zod.number().min(1).describe('Width, in grid columns.'),
h: zod.number().min(1).describe('Height, in grid rows.'),
config: zod
.record(zod.string(), zod.unknown())
.nullish()
.describe(
"Per-placement settings, validated against the component's configSchema."
),
prompt: zod
.string()
.max(canvasesLayoutPatchCreateBodyOperationsItemPlacementOnePromptMax)
.nullish()
.describe(
'For pending\/generating\/failed placements: what the user asked this box to become.'
),
generationTaskId: zod
.string()
.nullish()
.describe(
'Id of the agent task currently filling this placement, when one is running.'
),
})
.describe('One placed widget on a grid canvas.')
.optional()
.describe('For add_placement: the placement to add.'),
id: zod
.string()
.max(canvasesLayoutPatchCreateBodyOperationsItemIdMax)
.optional()
.describe('For update_placement\/remove_placement: the target placement id.'),
changes: zod
.object({
status: zod
.enum(['pending', 'generating', 'live', 'failed'])
.describe(
'\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed'
)
.optional()
.describe(
"Placement lifecycle: 'pending' (box drawn, no prompt yet), 'generating' (an agent task is filling it), 'live' (renders its component), 'failed' (generation failed; re-prompt or remove).\n\n\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed"
),
component: zod
.string()
.nullish()
.describe(
'Id of the component canvas this placement renders. Required once the placement is live.'
),
version: zod
.string()
.nullish()
.describe(
'Component version to render: \"latest\" (the default — follows the component\'s published build) or a pinned source version id.'
),
x: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemChangesOneXMin)
.optional()
.describe('Left edge, in grid columns (0-based).'),
y: zod
.number()
.min(canvasesLayoutPatchCreateBodyOperationsItemChangesOneYMin)
.optional()
.describe('Top edge, in grid rows (0-based).'),
w: zod.number().min(1).optional().describe('Width, in grid columns.'),
h: zod.number().min(1).optional().describe('Height, in grid rows.'),
config: zod
.record(zod.string(), zod.unknown())
.nullish()
.describe(
"Per-placement settings, validated against the component's configSchema."
),
prompt: zod
.string()
.max(canvasesLayoutPatchCreateBodyOperationsItemChangesOnePromptMax)
.nullish()
.describe(
'For pending\/generating\/failed placements: what the user asked this box to become.'
),
generationTaskId: zod
.string()
.nullish()
.describe(
'Id of the agent task currently filling this placement, when one is running.'
),
})
.describe('Fields to merge into an existing placement (all optional; id cannot change).')
.optional()
.describe('For update_placement: the fields to merge into the placement.'),
})
.describe('One surgical layout operation.')
)
.describe("Operations applied in order to the canvas's current layout, at most 64."),
prompt: zod
.string()
.optional()
.describe('Short description of the change, stored on the appended version history entry.'),
expected_current_version_id: zod
.string()
.nullable()
.describe(
'Required optimistic-concurrency guard: the current_version_id the operations are based on (null when the canvas has no layout versions yet). A moved head is rejected with 409 version_conflict — patches cannot apply unguarded.'
),
})
.describe("Payload for applying surgical operations to the canvas's current layout.")
/**
* Publish a complete layout document as the grid canvas's new head version.
*
* Layout is data, not code: the new version is live immediately, with no
* build. Validation errors reject the publish (400) and leave the canvas
* untouched; a stale `expected_current_version_id` is rejected with 409.
*/
export const CanvasesLayoutPublishCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesLayoutPublishCreateBodyLayoutOneGridOneRowHeightMin = 24
export const canvasesLayoutPublishCreateBodyLayoutOneGridOneRowHeightMax = 400
export const canvasesLayoutPublishCreateBodyLayoutOneGridOneGapMin = 0
export const canvasesLayoutPublishCreateBodyLayoutOneGridOneGapMax = 48
export const canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemIdMax = 64
export const canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemIdRegExp = new RegExp('^[A-Za-z0-9_-]{1,64}$')
export const canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemXMin = 0
export const canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemYMin = 0
export const canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemPromptMax = 10000
export const CanvasesLayoutPublishCreateBody = () => zod
.object({
layout: zod
.object({
schemaVersion: zod
.literal(1)
.describe('\* `1` - 1')
.describe('Layout schema version. Currently always 1.\n\n\* `1` - 1'),
grid: zod
.object({
columns: zod
.union([zod.literal(4), zod.literal(6), zod.literal(8), zod.literal(10), zod.literal(12)])
.describe('\* `4` - 4\n\* `6` - 6\n\* `8` - 8\n\* `10` - 10\n\* `12` - 12')
.describe(
'Grid width in columns. One of 4, 6, 8, 10, or 12.\n\n\* `4` - 4\n\* `6` - 6\n\* `8` - 8\n\* `10` - 10\n\* `12` - 12'
),
rowHeight: zod
.number()
.min(canvasesLayoutPublishCreateBodyLayoutOneGridOneRowHeightMin)
.max(canvasesLayoutPublishCreateBodyLayoutOneGridOneRowHeightMax)
.describe('Height of one grid row, in pixels.'),
gap: zod
.number()
.min(canvasesLayoutPublishCreateBodyLayoutOneGridOneGapMin)
.max(canvasesLayoutPublishCreateBodyLayoutOneGridOneGapMax)
.describe('Gap between placements, in pixels.'),
})
.describe('The grid a grid canvas lays its placements out on.')
.describe('The grid placements are laid out on.'),
placements: zod
.array(
zod
.object({
id: zod
.string()
.max(canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemIdMax)
.regex(canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemIdRegExp)
.describe(
"Stable placement id, unique within the layout. 1-64 characters of letters, digits, '_', or '-'."
),
status: zod
.enum(['pending', 'generating', 'live', 'failed'])
.describe(
'\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed'
)
.describe(
"Placement lifecycle: 'pending' (box drawn, no prompt yet), 'generating' (an agent task is filling it), 'live' (renders its component), 'failed' (generation failed; re-prompt or remove).\n\n\* `pending` - pending\n\* `generating` - generating\n\* `live` - live\n\* `failed` - failed"
),
component: zod
.string()
.nullish()
.describe(
'Id of the component canvas this placement renders. Required once the placement is live.'
),
version: zod
.string()
.nullish()
.describe(
'Component version to render: \"latest\" (the default — follows the component\'s published build) or a pinned source version id.'
),
x: zod
.number()
.min(canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemXMin)
.describe('Left edge, in grid columns (0-based).'),
y: zod
.number()
.min(canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemYMin)
.describe('Top edge, in grid rows (0-based).'),
w: zod.number().min(1).describe('Width, in grid columns.'),
h: zod.number().min(1).describe('Height, in grid rows.'),
config: zod
.record(zod.string(), zod.unknown())
.nullish()
.describe(
"Per-placement settings, validated against the component's configSchema."
),
prompt: zod
.string()
.max(canvasesLayoutPublishCreateBodyLayoutOnePlacementsItemPromptMax)
.nullish()
.describe(
'For pending\/generating\/failed placements: what the user asked this box to become.'
),
generationTaskId: zod
.string()
.nullish()
.describe(
'Id of the agent task currently filling this placement, when one is running.'
),
})
.describe('One placed widget on a grid canvas.')
)
.describe('The placed widgets, at most 24. Placements may not overlap or extend past the grid.'),
})
.describe("A grid canvas's layout document — its entire 'source'.")
.describe('The complete layout document to publish.'),
prompt: zod
.string()
.optional()
.describe('Short description of the change, stored on the appended version history entry.'),
expected_current_version_id: zod
.string()
.nullish()
.describe(
'Optimistic-concurrency guard: the current_version_id the layout was based on (null when the canvas has no versions yet). A moved head is rejected with 409 version_conflict. Omit to publish unguarded.'
),
})
.describe('Payload for publishing a complete layout document.')
/**
* Make a draft version the canvas's live head.
*
* A draft whose build is ready goes live immediately, with no rebuild;
* otherwise a fresh build is queued. Returns that build.
*/
export const CanvasesPromoteCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesPromoteCreateBody = () => zod
.object({
version_id: zod.string().describe('Id of the draft source version to make live.'),
expected_current_version_id: zod
.string()
.nullable()
.describe(
'Current source version observed before requesting the promote (null when the canvas has never been published). A moved head is rejected with 409 version_conflict.'
),
})
.describe("Payload for promoting a draft version to the canvas's live head.")
/**
* Publish a complete source project as the canvas's new head version.
*
* Validation errors reject the publish (400) and leave the canvas
* untouched; a stale `expected_current_version_id` is rejected with 409.
* A successful publish queues a server-side build.
*/
export const CanvasesPublishCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesPublishCreateBodyProjectOneAssetsContentMax = 2796204
export const canvasesPublishCreateBodyProjectOneAssetsContentRegExp = new RegExp(
'^(?:[A-Za-z0-9+\/]{4})\*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$'
)
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneDefaultWMax = 12
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneDefaultHMax = 40
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneMinWMax = 12
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneMinHMax = 40
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneMaxWMax = 12
export const canvasesPublishCreateBodyProjectOneComponentOneSizeOneMaxHMax = 40
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax = 128
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax = 100
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax = 200
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax = 100
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogStateMax = 2
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax = 64
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogActionsMax = 32
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax = 200
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogToolsMax = 32
export const canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault = false
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax = 2048
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax = 20
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax = 300
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax = 200
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax = 64
export const canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsMax = 20
export const canvasesPublishCreateBodyNameMax = 400
export const CanvasesPublishCreateBody = () => zod
.object({
project: zod
.object({
schemaVersion: zod.number().describe('Source-project schema version. Currently always 1.'),
files: zod
.record(zod.string(), zod.string())
.describe("Project files keyed by relative path (forward slashes, no '..')."),
assets: zod
.record(
zod.string(),
zod.object({
encoding: zod.enum(['base64']).describe('\* `base64` - base64'),
contentType: zod
.enum([
'image/png',
'image/jpeg',
'image/gif',
'image/webp',
'image/svg+xml',
'font/woff',
'font/woff2',
'application/wasm',
'application/octet-stream',
])
.describe(
'\* `image\/png` - image\/png\n\* `image\/jpeg` - image\/jpeg\n\* `image\/gif` - image\/gif\n\* `image\/webp` - image\/webp\n\* `image\/svg+xml` - image\/svg+xml\n\* `font\/woff` - font\/woff\n\* `font\/woff2` - font\/woff2\n\* `application\/wasm` - application\/wasm\n\* `application\/octet-stream` - application\/octet-stream'
),
content: zod
.string()
.max(canvasesPublishCreateBodyProjectOneAssetsContentMax)
.regex(canvasesPublishCreateBodyProjectOneAssetsContentRegExp),
})
)
.optional()
.describe('Optional base64-encoded binary assets keyed by safe project-relative paths.'),
entryHtml: zod.string().describe('The project\'s entry HTML file. Currently always \"index.html\".'),
dependencies: zod
.record(zod.string(), zod.string())
.optional()
.describe(
'Exact-version dependencies, restricted to the platform-supported set at its pinned versions.'
),
canvasSdkVersion: zod
.string()
.optional()
.describe('Version of the host-injected `ph` canvas SDK the project targets.'),
component: zod
.object({
size: zod
.object({
defaultW: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneDefaultWMax)
.describe('Width a new placement starts at, in grid columns.'),
defaultH: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneDefaultHMax)
.describe('Height a new placement starts at, in grid rows.'),
minW: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneMinWMax)
.describe('Narrowest width the component renders usefully at.'),
minH: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneMinHMax)
.describe('Shortest height the component renders usefully at.'),
maxW: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneMaxWMax)
.optional()
.describe("Widest allowed width; omit for no cap below the grid's width."),
maxH: zod
.number()
.min(1)
.max(canvasesPublishCreateBodyProjectOneComponentOneSizeOneMaxHMax)
.optional()
.describe('Tallest allowed height; omit for no cap.'),
})
.describe("A component's grid-size contract, in grid units.")
.describe('Grid-size contract for placements of this component.'),
configSchema: zod
.record(zod.string(), zod.unknown())
.optional()
.describe(
'JSON Schema (\"type\": \"object\") for a placement\'s config. The host validates each placement\'s config against it and passes the validated object to the widget at mount.'
),
})
.describe("A component's placement contract: how grid canvases may place and configure it.")
.optional()
.describe(
'Placement contract, required for (and only allowed on) component-kind canvases: the grid size the component takes and the JSON Schema of its per-placement config.'
),
capabilities: zod
.object({
posthog: zod.object({
insights: zod
.array(
zod
.string()
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax),
inlineQueries: zod.boolean(),
captureEvents: zod
.array(
zod
.string()
.max(
canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax
)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax),
state: zod
.array(zod.enum(['user', 'shared']).describe('\* `user` - user\n\* `shared` - shared'))
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogStateMax)
.optional()
.describe(
"State scopes the canvas may use via ph.state: 'user' (private to each viewer) and\/or 'shared' (one value per canvas, team-visible)."
),
actions: zod
.array(
zod
.string()
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogActionsMax)
.optional()
.describe(
"Registered action verbs the canvas may invoke via ph.actions (e.g. 'annotations.create', 'tasks.create'). Each executes as the viewer; declaring one shows it in the promote review."
),
tools: zod
.array(
zod
.string()
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogToolsMax)
.optional()
.describe(
"PostHog MCP tools the canvas may run via ph.tools (e.g. 'feature-flag-get-definition', 'feature-flag-set-release-condition-rollout'). Each runs as the viewer; declaring one shows it in the promote review."
),
agentRequests: zod
.boolean()
.default(canvasesPublishCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault),
}),
network: zod.object({
origins: zod
.array(
zod
.url()
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax),
}),
connectors: zod
.array(
zod
.object({
provider: zod
.string()
.max(
canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax
)
.describe(
"Connector provider id: a native provider such as 'github', or 'mcp:<server host>' (e.g. 'mcp:mcp.calendly.com') for a server the viewer connected in the MCP store."
),
tools: zod
.array(
zod
.string()
.max(
canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax
)
)
.min(1)
.max(
canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax
)
.describe(
'Tool names the canvas may call on this provider. Read-only tools only.'
),
})
.describe(
'One provider a canvas may call through ph.connectors, with the tools it may use.'
)
)
.max(canvasesPublishCreateBodyProjectOneCapabilitiesOneConnectorsMax)
.optional()
.describe(
"Third-party providers the canvas reads through ph.connectors, each with the tools it may call. Every call runs with the viewer's own connection; declaring one shows it in the promote review."
),
})
.optional()
.describe(
'Bounded capabilities frozen into the built artifact. Declare every insight short id the canvas loads, every event it captures, and inlineQueries when it runs ad-hoc HogQL — the host enforces these at runtime and validation rejects undeclared `ph` calls. Network origins must be exact HTTPS origins. Data fetched by canvas code can be sent to those origins.'
),
})
.describe("A canvas's multi-file source project — the canonical write format for canvas source.")
.describe('The complete source project to publish.'),
prompt: zod
.string()
.optional()
.describe('Short description of the change, stored on the appended version history entry.'),
name: zod
.string()
.max(canvasesPublishCreateBodyNameMax)
.optional()
.describe('Optional new display name for the canvas.'),
expected_current_version_id: zod
.string()
.nullish()
.describe(
'Optimistic-concurrency guard: the current_version_id the publisher based its edits on (null when it read a canvas with no versions yet). When the canvas has since moved past it the publish is rejected with a 409 version_conflict instead of overwriting the newer head. Omit to publish unguarded.'
),
})
.describe('Payload for publishing a complete canvas source project.')
/**
* Queue a build for the current source version without changing source or metadata.
*/
export const CanvasesPublishCurrentVersionCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesPublishCurrentVersionCreateBody = () => zod.object({
expected_current_version_id: zod
.string()
.describe('Current source version to publish. A changed head returns a 409 version_conflict.'),
})
/**
* Read the canvas's source project and its `current_version_id`.
*
* Always call this before editing: edit the returned files, then publish
* the complete project passing the returned version id as
* `expected_current_version_id` so concurrent edits are not overwritten.
* `?version_id=` reads a historical version instead of the head.
*/
export const CanvasesSourceRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesSourceRetrieveQueryParams = () => zod.object({
version_id: zod
.string()
.optional()
.describe('Read this historical source version instead of the head (for version browsing).'),
})
/**
* Read the canvas's runtime key-value state (the ph.state store).
*
* Returns shared entries plus the authenticated user's own user-scoped
* entries — never another user's.
*/
export const CanvasesStateRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesStateRetrieveQueryCursorMax = 2048
export const canvasesStateRetrieveQueryKeyMax = 200
export const canvasesStateRetrieveQueryKeyPrefixMax = 200
export const canvasesStateRetrieveQueryKeysOnlyDefault = false
export const canvasesStateRetrieveQueryLimitMax = 100
export const canvasesStateRetrieveQueryOffsetDefault = 0
export const canvasesStateRetrieveQueryOffsetMin = 0
export const CanvasesStateRetrieveQueryParams = () => zod.object({
cursor: zod
.string()
.min(1)
.max(canvasesStateRetrieveQueryCursorMax)
.optional()
.describe(
'Cursor from next_cursor. Resumes after the last entry of the previous page, so an entry that exists for the whole read comes back exactly once. A key written between pages can be missing. Keep filters unchanged between pages. Takes precedence over offset.'
),
key: zod.string().min(1).max(canvasesStateRetrieveQueryKeyMax).optional().describe('Only read this exact key.'),
key_prefix: zod
.string()
.max(canvasesStateRetrieveQueryKeyPrefixMax)
.optional()
.describe('Only read entries whose key starts with this prefix.'),
keys_only: zod
.boolean()
.default(canvasesStateRetrieveQueryKeysOnlyDefault)
.describe('True returns a key inventory without stored values.'),
limit: zod
.number()
.min(1)
.max(canvasesStateRetrieveQueryLimitMax)
.optional()
.describe(
'Maximum entries per page. Omit for the full state. Prefer an inventory and state\/value for large values.'
),
offset: zod
.number()
.min(canvasesStateRetrieveQueryOffsetMin)
.default(canvasesStateRetrieveQueryOffsetDefault)
.describe(
'Entry offset from next_offset. Keep filters unchanged between pages. Prefer cursor: an offset can skip or repeat entries when state changes between pages.'
),
scope: zod
.enum(['user', 'shared'])
.optional()
.describe('Only read this scope.\n\n\* `user` - user\n\* `shared` - shared'),
})
/**
* Write one key of the canvas's runtime state, or delete it with a null value.
*/
export const CanvasesStateSetParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesStateSetBodyKeyMax = 200
export const CanvasesStateSetBody = () => zod
.object({
scope: zod
.enum(['user', 'shared'])
.describe('\* `user` - user\n\* `shared` - shared')
.describe(
'Scope to write into; the canvas must declare it in capabilities.posthog.state.\n\n\* `user` - user\n\* `shared` - shared'
),
key: zod.string().max(canvasesStateSetBodyKeyMax).describe('Key to write, unique within its scope.'),
value: zod.unknown().describe('JSON value to store (at most 64 KB serialized), or null to delete the key.'),
})
.describe("Payload for writing (or deleting) one key of a canvas's runtime state.")
/**
* Canvases: agent-built sandboxed browser apps, filed into channels.
*
* Source is versioned per publish and built server-side; the canvas app
* renders the published build's artifact from the isolated artifact origin.
*/
export const CanvasesStateValueRetrieveParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesStateValueRetrieveQueryKeyMax = 200
export const canvasesStateValueRetrieveQueryLimitDefault = 12000
export const canvasesStateValueRetrieveQueryLimitMax = 12000
export const canvasesStateValueRetrieveQueryOffsetDefault = 0
export const canvasesStateValueRetrieveQueryOffsetMin = 0
export const canvasesStateValueRetrieveQueryRevisionMax = 64
export const CanvasesStateValueRetrieveQueryParams = () => zod.object({
key: zod.string().min(1).max(canvasesStateValueRetrieveQueryKeyMax).describe('Exact key to read.'),
limit: zod
.number()
.min(1)
.max(canvasesStateValueRetrieveQueryLimitMax)
.default(canvasesStateValueRetrieveQueryLimitDefault)
.describe('Maximum JSON characters in this response.'),
offset: zod
.number()
.min(canvasesStateValueRetrieveQueryOffsetMin)
.default(canvasesStateValueRetrieveQueryOffsetDefault)
.describe('Character offset from next_offset.'),
revision: zod
.string()
.min(1)
.max(canvasesStateValueRetrieveQueryRevisionMax)
.optional()
.describe('Revision from the first chunk. Required when offset is greater than zero.'),
scope: zod
.enum(['user', 'shared'])
.describe('Scope of the value to read.\n\n\* `user` - user\n\* `shared` - shared'),
})
/**
* Validate a candidate source project without publishing it. Side-effect free.
*/
export const CanvasesValidateCreateParams = () => zod.object({
id: zod.string().describe('A UUID string identifying this canvas.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const canvasesValidateCreateBodyProjectOneAssetsContentMax = 2796204
export const canvasesValidateCreateBodyProjectOneAssetsContentRegExp = new RegExp(
'^(?:[A-Za-z0-9+\/]{4})\*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$'
)
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneDefaultWMax = 12
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneDefaultHMax = 40
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneMinWMax = 12
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneMinHMax = 40
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneMaxWMax = 12
export const canvasesValidateCreateBodyProjectOneComponentOneSizeOneMaxHMax = 40
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax = 128
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax = 100
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax = 200
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax = 100
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogStateMax = 2
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax = 64
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogActionsMax = 32
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax = 200
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogToolsMax = 32
export const canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault = false
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax = 2048
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax = 20
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax = 300
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax = 200
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax = 64
export const canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsMax = 20
export const CanvasesValidateCreateBody = () => zod
.object({
project: zod
.object({
schemaVersion: zod.number().describe('Source-project schema version. Currently always 1.'),
files: zod
.record(zod.string(), zod.string())
.describe("Project files keyed by relative path (forward slashes, no '..')."),
assets: zod
.record(
zod.string(),
zod.object({
encoding: zod.enum(['base64']).describe('\* `base64` - base64'),
contentType: zod
.enum([
'image/png',
'image/jpeg',
'image/gif',
'image/webp',
'image/svg+xml',
'font/woff',
'font/woff2',
'application/wasm',
'application/octet-stream',
])
.describe(
'\* `image\/png` - image\/png\n\* `image\/jpeg` - image\/jpeg\n\* `image\/gif` - image\/gif\n\* `image\/webp` - image\/webp\n\* `image\/svg+xml` - image\/svg+xml\n\* `font\/woff` - font\/woff\n\* `font\/woff2` - font\/woff2\n\* `application\/wasm` - application\/wasm\n\* `application\/octet-stream` - application\/octet-stream'
),
content: zod
.string()
.max(canvasesValidateCreateBodyProjectOneAssetsContentMax)
.regex(canvasesValidateCreateBodyProjectOneAssetsContentRegExp),
})
)
.optional()
.describe('Optional base64-encoded binary assets keyed by safe project-relative paths.'),
entryHtml: zod.string().describe('The project\'s entry HTML file. Currently always \"index.html\".'),
dependencies: zod
.record(zod.string(), zod.string())
.optional()
.describe(
'Exact-version dependencies, restricted to the platform-supported set at its pinned versions.'
),
canvasSdkVersion: zod
.string()
.optional()
.describe('Version of the host-injected `ph` canvas SDK the project targets.'),
component: zod
.object({
size: zod
.object({
defaultW: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneDefaultWMax)
.describe('Width a new placement starts at, in grid columns.'),
defaultH: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneDefaultHMax)
.describe('Height a new placement starts at, in grid rows.'),
minW: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneMinWMax)
.describe('Narrowest width the component renders usefully at.'),
minH: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneMinHMax)
.describe('Shortest height the component renders usefully at.'),
maxW: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneMaxWMax)
.optional()
.describe("Widest allowed width; omit for no cap below the grid's width."),
maxH: zod
.number()
.min(1)
.max(canvasesValidateCreateBodyProjectOneComponentOneSizeOneMaxHMax)
.optional()
.describe('Tallest allowed height; omit for no cap.'),
})
.describe("A component's grid-size contract, in grid units.")
.describe('Grid-size contract for placements of this component.'),
configSchema: zod
.record(zod.string(), zod.unknown())
.optional()
.describe(
'JSON Schema (\"type\": \"object\") for a placement\'s config. The host validates each placement\'s config against it and passes the validated object to the widget at mount.'
),
})
.describe("A component's placement contract: how grid canvases may place and configure it.")
.optional()
.describe(
'Placement contract, required for (and only allowed on) component-kind canvases: the grid size the component takes and the JSON Schema of its per-placement config.'
),
capabilities: zod
.object({
posthog: zod.object({
insights: zod
.array(
zod
.string()
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogInsightsItemMax)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogInsightsMax),
inlineQueries: zod.boolean(),
captureEvents: zod
.array(
zod
.string()
.max(
canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsItemMax
)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogCaptureEventsMax),
state: zod
.array(zod.enum(['user', 'shared']).describe('\* `user` - user\n\* `shared` - shared'))
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogStateMax)
.optional()
.describe(
"State scopes the canvas may use via ph.state: 'user' (private to each viewer) and\/or 'shared' (one value per canvas, team-visible)."
),
actions: zod
.array(
zod
.string()
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogActionsItemMax)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogActionsMax)
.optional()
.describe(
"Registered action verbs the canvas may invoke via ph.actions (e.g. 'annotations.create', 'tasks.create'). Each executes as the viewer; declaring one shows it in the promote review."
),
tools: zod
.array(
zod
.string()
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogToolsItemMax)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogToolsMax)
.optional()
.describe(
"PostHog MCP tools the canvas may run via ph.tools (e.g. 'feature-flag-get-definition', 'feature-flag-set-release-condition-rollout'). Each runs as the viewer; declaring one shows it in the promote review."
),
agentRequests: zod
.boolean()
.default(
canvasesValidateCreateBodyProjectOneCapabilitiesOnePosthogAgentRequestsDefault
),
}),
network: zod.object({
origins: zod
.array(
zod
.url()
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOneNetworkOriginsItemMax)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOneNetworkOriginsMax),
}),
connectors: zod
.array(
zod
.object({
provider: zod
.string()
.max(
canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemProviderMax
)
.describe(
"Connector provider id: a native provider such as 'github', or 'mcp:<server host>' (e.g. 'mcp:mcp.calendly.com') for a server the viewer connected in the MCP store."
),
tools: zod
.array(
zod
.string()
.max(
canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsItemMax
)
)
.min(1)
.max(
canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsItemToolsMax
)
.describe(
'Tool names the canvas may call on this provider. Read-only tools only.'
),
})
.describe(
'One provider a canvas may call through ph.connectors, with the tools it may use.'
)
)
.max(canvasesValidateCreateBodyProjectOneCapabilitiesOneConnectorsMax)
.optional()
.describe(
"Third-party providers the canvas reads through ph.connectors, each with the tools it may call. Every call runs with the viewer's own connection; declaring one shows it in the promote review."
),
})
.optional()
.describe(
'Bounded capabilities frozen into the built artifact. Declare every insight short id the canvas loads, every event it captures, and inlineQueries when it runs ad-hoc HogQL — the host enforces these at runtime and validation rejects undeclared `ph` calls. Network origins must be exact HTTPS origins. Data fetched by canvas code can be sent to those origins.'
),
})
.describe("A canvas's multi-file source project — the canonical write format for canvas source.")
.describe('The candidate source project to validate.'),
})
.describe('Payload for validating a candidate source project without publishing it.')
/**
* List the connector catalog: every provider and tool a canvas may declare, with the caller's connection state.
*
* Authoring agents read this to write ph.connectors.call sites and the
* matching capabilities.connectors declarations. Sandbox tokens receive
* only static native tools, with no connection lookup or MCP installation data.
*/
export const CanvasesConnectorsRetrieveParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const CanvasesConnectorsRetrieveQueryParams = () => zod.object({
mcp_hosts: zod
.string()
.optional()
.describe(
"Comma-separated MCP server hosts to include (e.g. 'mcp.calendly.com'). Defaults to every server the caller has connected in the MCP store."
),
})