Pages

Create, read and rewrite HTML page artifacts under a required version check. Every page renders with the workspace’s design.md css — read it first with read_theme and use its classes.

Tool	Scope	Kind
`create_page`	`documents:write`	write
`read_page`	`documents:read`	read-only
`write_page`	`documents:write`	write, destructive

create_page

Scope: documents:write (step-up) · Kind: write · Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

Create an HTML page artifact in the person’s library with a scope: user (private, the default) or org, optionally filed into a folder (folder_id). The HTML source is stored verbatim, but pages render inert: <script>/<iframe>/<object>/<embed>, every on* event-handler attribute and every javascript:/vbscript:/data:text/html URL are removed at render, in a sandboxed frame with no scripts and a default-src 'none' CSP. A script_stripped warning tells you when that will happen. Returns — url is the link to share with people, version what write_page requires.

Parameters

Pass a scope, optionally with folder_id.

string

required

string

The page’s HTML, stored verbatim. Must be non-empty. Required unless upload_id is given.

string

Instead of html: the id from request_upload_url (format html) after the file was uploaded. Use it for a file already on disk or anything over about 8 KB. Never pass both.

'user' | 'org'

default:"user"

Where the page lives.

string

With a scope: file the page straight into this folder (from list_folders). You must be its owner or a participant.

Returns

string

The artifact id. Use it as page_id for read_page and write_page, and as document_id for comments and export.

string

The web-app link the page opens at (https://sidecars.ai/artifacts/<page_id>) — share this one, never a guessed path.

string

number

The version write_page must pass as expected_version.

number

string[]

["script_stripped"] when the HTML contains anything the renderer removes: <script>, <iframe>, <object> or <embed> elements, on* event-handler attributes (onload, onerror, onfocus, onmouseover, … on any element, SVG included), or javascript:, vbscript: and data:text/html URLs in URL attributes (href, src, srcdoc, action, formaction, xlink:href, …), entity- or whitespace-encoded or not. They stay in the stored source but are removed when the page is viewed, so its interactivity will not run.

Text: Created page "<title>" (page_id: <id>, version <n>) — <url>. plus Note: its scripts, embedded elements, event handlers and script URLs will be removed when viewed. when applicable.

Permissions and side effects

Needs documents:write.
The access gate runs inside the create transaction: with folder_id you must be the folder’s owner or a participant.
The caller becomes the owner; nothing is posted anywhere.

Errors

Text	Cause
`Tool failed: \`scope` must be user \| org`	Unknown scope
`Tool failed: Pods and rooms are gone from Sidecars …`	A `pod_id`, `conversation_id` or `scope: "pod"` was passed; use `list_folders` and `folder_id`
`Tool failed: … Folder not found`	A folder you cannot open

Limitations

No idempotency key on this tool; a retried create makes a second page.
Pages run no code. The viewer and the downloadable rendition are both the stripped page (see warnings above), shown in a sandboxed iframe without allow-scripts, under a default-src 'none' Content-Security-Policy that permits only inline styles and data:/same-origin images and fonts. Style with inline CSS; there is no way to run JavaScript in a page.

Example

Request

{
  "name": "create_page",
  "arguments": {
    "scope": "user",
    "title": "Acme rollout timeline",
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>"
  }
}

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "url": "https://sidecars.ai/artifacts/k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "version": 1,
  "byte_size": 104,
  "warnings": []
}

read_page

Scope: documents:read (step-up) · Kind: read-only · Annotations: readOnlyHint: true, destructiveHint: false, openWorldHint: false

Read a page’s stored HTML source and its version — the token write_page’s expected_version is checked against. This is the source as written, not what viewers get: pages render with scripts, event handlers, javascript:/vbscript:/data:text/html URLs and iframe/object/embed removed, in a sandboxed script-less frame.

Parameters

string

required

The page’s artifact id.

Returns

string

The stored source as written, scripts and handlers included. Viewers never receive it: the rendered page has them removed (see create_page warnings).

number

Pass as expected_version to write_page.

Text: # <title> (version <n>) followed by the HTML.

Permissions and side effects

Needs documents:read and any role on the page. The access check and the source read happen in one transaction.
Reads only. Recorded in the agent activity history.

Errors

Text	Cause
`That artifact is a document, not an HTML page — use read_document.`	The id names a document or table
`That page has no content yet.`	The page exists but has no stored source
`Tool failed: … Artifact not found`	Not visible, wrong workspace or no such id

Example

Request

{ "name": "read_page", "arguments": { "page_id": "k55timeline0example000000000000000" } }

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>",
  "version": 1
}

write_page

Scope: documents:write (step-up) · Kind: write, destructive · Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false

Replace a page’s HTML wholesale. expected_version is REQUIRED — the version read_page (or create_page) returned. If the page moved since your read, the write refuses with the current version and a line-level diff of what changed, so you can merge and retry; there is no force flag, by design. The source is stored verbatim; at render, scripts, on* handlers, javascript:/vbscript:/data:text/html URLs and iframe/object/embed are removed and the page runs in a sandboxed, script-less, CSP-locked frame.

Parameters

string

required

string

The complete new HTML. Must be non-empty. Required unless upload_id is given.

string

Instead of html: the id from request_upload_url (format html) after the file was uploaded. Use it for a file already on disk or anything over about 8 KB. Never pass both.

number

required

The version read_page or create_page returned. Must be a non-negative integer.

Returns

string

number

string[]

["script_stripped"] when the HTML carries anything the renderer removes (same rule as create_page).

Text: Wrote the page; it is now at version <n> (<bytes> bytes).

Permissions and side effects

Needs documents:write and the editor or owner role. The role is re-checked inside the write transaction.
Replaces the whole page. The previous source is kept as a checkpoint.
Attributed to you via the host.

Errors

`error`	Text (abridged)	What to do
—	`Tool failed: \`expected_version` must be a non-negative integer`	Pass the integer from your read
—	`That artifact is a document, not an HTML page — use edit_document.`	Use `edit_document`
—	`That artifact is a table, not an HTML page. …`	Tables are not editable
`version_conflict`	`The page moved from version A to B since you read it. What changed:\n<diff>\nMerge your changes onto the current page (read_page) and write again with expected_version B.`	Merge and retry; `diff_excerpt` and `changed_range` are included when available
—	`Tool failed: … This document is read-only for you`	You are a viewer
—	`Tool failed: … You can comment on this document but not edit it`	You are a commenter
—	`Tool failed: … This document is archived`	Archived
—	`Tool failed: … Artifact not found`	Not visible, wrong workspace or no such id

There is deliberately no way to overwrite a newer version without reading it first.

Example

Request

{
  "name": "write_page",
  "arguments": {
    "page_id": "k55timeline0example000000000000000",
    "expected_version": 1,
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — December</li></ol>"
  }
}

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "new_version": 2,
  "byte_size": 103,
  "warnings": []
}

Conflict response (structuredContent)

{
  "error": "version_conflict",
  "expected_version": 1,
  "current_version": 3,
  "diff_excerpt": "-<li>GA — November</li>\n+<li>GA — 2 December</li>"
}

Get started

Use it

Reference

create_page

Parameters

Returns

Permissions and side effects

Errors

Limitations

Example

read_page

Parameters

Returns

Permissions and side effects

Errors

Example

write_page

Parameters

Returns

Permissions and side effects

Errors

Example

​create_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Limitations

​Example

​read_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

​write_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

create_page

Parameters

Returns

Permissions and side effects

Errors

Limitations

Example

read_page

Parameters

Returns

Permissions and side effects

Errors

Example

write_page

Parameters

Returns

Permissions and side effects

Errors

Example