Create Pane
create_paneHand a human an interactive UI by URL to collect structured data or approval. Build inline HTML or reuse a template; returns a URL to share.
Instructions
Hand the human a rich interactive UI by URL and (optionally) get structured data back. Build the UI as inline HTML (pass name + html) OR reuse a saved template (pass template_id). The relay hosts it and returns a URL. ALWAYS give the returned url to the human — paste it into the conversation and ask them to open it. Reach for this whenever a text reply is the wrong shape: forms, approvals, pickers, surveys, dashboards, diff/doc review, wizards. If the page captures input it emits events back to you (poll them with get_events) or mutates record collections (the record tools). BEFORE authoring: call get_skill for the events-vs-records decision + schema grammar, and the taste tool (action: get) for the human's house style — both shape the HTML you write. Returns { pane_id, url, urls, title, expires_at }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | The pane's UI as a complete inline HTML document. To send data back to you, the page calls window.pane.emit(eventType, payload) — every emitted eventType MUST be declared in event_schema with 'page' in its emittedBy. Read window.pane.inputData for seed data. Pass EITHER `html` (+`name`) for a one-off, OR `template_id` to reuse a saved template — not both. | |
| name | No | Short human-readable label for the auto-created template (e.g. 'Deploy approval'). REQUIRED when you pass `html` (inline form); omit when reusing an existing template via `template_id` (it inherits the template's name). | |
| tags | No | Optional per-pane filter tags (merged with the template's tags). ≤20 tags, ≤50 chars each; 'favorite'/'favorites' are reserved. | |
| title | No | Optional browser tab title for the human (≤80 chars). Defaults to `name`. | |
| callback | No | Optional webhook callback config so the relay POSTs new events to your endpoint. Shape per the relay's callback schema (e.g. { url, secret? }). Most MCP agents poll with get_events instead. | |
| metadata | No | Optional opaque JSON you can attach to the pane for your own bookkeeping (never shown to the human, queryable via run_query). | |
| preamble | No | Optional one/two-line context shown above the UI — 'who is asking, and why'. | |
| icon_emoji | No | Optional single-emoji icon override for this pane. | |
| input_data | No | Optional seed data for this pane instance, readable in the page as window.pane.inputData (e.g. the diff to review, the options to pick from). | |
| context_key | No | Optional natural key (e.g. 'pr-42'). Repeated create_pane calls with the same (template, key) return the SAME pane — makes retries idempotent. | |
| template_id | No | Reuse an existing named template (id or slug) instead of inline HTML. The template's pinned version supplies the HTML + event/input/record schemas. Mutually exclusive with `html`/`name`/`event_schema`/`input_schema`. Create templates with the `template` tool. | |
| ttl_seconds | No | Optional pane lifetime in seconds. The relay clamps to its max; the returned expires_at is authoritative. | |
| event_schema | No | Inline form only. Declares which events the page (and you) may emit and validates each payload. Shape: { events: { '<type>': { emittedBy: ['page'|'agent'...], payload: <JSON Schema> } } }. OMIT for a read-only pane. | |
| input_schema | No | Inline form only. Optional JSON Schema validating input_data. Needed if input_data references uploaded attachment ids the page must download. | |
| participants | No | Optional number of distinct human participant URLs to mint (default 1). Each gets its own URL in the returned `urls` array. | |
| record_schema | No | Inline form only. JSON Schema 2020-12 doc with an `x-pane-collections` extension declaring this pane's mutable record collections (todos, comments…). OMIT for an event-only pane. | |
| template_version | No | With `template_id`: pin this pane to a specific template version. Defaults to the template head's latest version. | |
| icon_attachment_id | No | Optional per-pane icon as a ready raster-image attachment id (png/jpeg/webp/gif). Upload it first via the `attachments` tool (scope: pane or agent). |